From ticket queue to API call: a migration playbook for moving off legacy localization workflows

If your localization process still runs through a ticket queue, you already know the failure mode. A PM exports a batch of strings or drops a video file into a shared drive, files a request, and waits. Status updates arrive by email. A file comes back in the wrong format, or a language pair gets skipped, and someone has to notice before it ships. None of this is a people problem, it is an architecture problem. You're routing machine-speed work through a human intake form.

The fix is not a rip-and-replace of your vendor relationship. It is a staged migration: authenticate, upload, order, get notified, and govern, each stage shippable on its own, each one removing a manual handoff without breaking the stage before it. This playbook walks an engineering team through that sequence using Ollang's documented API surface, so you can start replacing ticket-driven handoffs with calls your pipeline makes itself.

Stage 1: Authenticate and prove connectivity before you build anything

Before writing integration code, confirm you can actually reach the platform. Ollang exposes a health check endpoint specifically for this, a 200 response with a status of OK confirms connectivity, and if this fails from your environment but works from your laptop, the issue is between your network and Ollang, not Ollang itself. That distinction matters on day one because it tells you immediately whether you're debugging a firewall rule or a credential.

This endpoint pings the Ollang API to verify it's online and requires no API key, which makes it usable as a pre-auth smoke test in CI, in a deploy pipeline, or as a standalone uptime probe before any real work flows through the system.

Once connectivity is confirmed, move to authenticated calls. Authentication uses an X-Api-Key header, and you obtain the key from your Ollang dashboard. If you hit auth errors, the two most common causes are confirming the header name is X-Api-Key, not Authorization or X-API-KEY, and confirming the key value is your active API key from the dashboard, especially if it was recently rotated. Get these details from Ollang's API documentation, rather than guessing at header conventions, auth mistakes are the most common reason a first integration stalls.

Stage 2: Replace the file handoff with a direct upload call

The ticket queue's core inefficiency is the file handoff itself, someone attaches a video, a contract, a spreadsheet of UI strings to an email or portal form, and a human on the other end has to route it. Direct file upload replaces that step with a single API call your own systems can trigger the moment content is ready.

The endpoint accepts the formats engineering teams actually deal with, including video formats such as MP4, AVI, MOV, WMV, FLV, and MKV; audio formats such as MP3, WAV, AAC, M4A, FLAC, and OGG; document formats such as DOCX, DOC, PDF, TXT, RTF, and ODT; presentation formats such as PPTX, PPT, and ODP; spreadsheet formats such as XLSX, XLS, ODS, and CSV, alongside HTML, XML, JSON, and subtitle formats. Size ceilings are large enough for production assets, with a maximum file size up to 30GB for video files and 100MB for document files.

A representative call looks like a standard multipart POST: calling the direct upload endpoint with the file, a name, and a source language returns a response you can act on programmatically, rather than a support ticket ID you have to track by hand. The response returns a project identifier, which becomes the anchor for every subsequent step, creating orders, running QC, requesting revisions. Full parameter details, including naming conventions and source-language codes, are in Ollang's Direct File Upload documentation.

One practical note for teams migrating at volume: very large video assets should go through this endpoint rather than a browser-based upload path, since the in-page API playground caps at 5 MB, and for very large videos you should prefer the Direct File Upload endpoint over web uploads.

Stage 3: Create orders programmatically and choose your review gate

Once a project exists, order creation is the step that used to require a form field for "target languages" and a dropdown for "review level," filed by a human and interpreted by another human. That becomes a single API call.

Order creation supports the order types that matter for engineering-adjacent localization work: closed captions, subtitles, document translation, AI dubbing, and studio dubbing. A call might look as simple as specifying a subtitle order for a given project in two target languages, and the response returns order identifiers you track going forward. Reference details on required fields and the full type list live in Ollang's Create Order and Order Types documentation.

The decision that matters most here is what happens to the output. Ollang's execution model gives you a review gate as a parameter, not a separate vendor negotiation. Orders can complete on AI translation alone, or you can route them for human review. A human review skill lets you upgrade or downgrade an order to linguist review, and the underlying operations exist as documented endpoints for requesting or cancelling that review, using Cancel Human Review to revert to the AI-only state and refund review credits if priorities change. The platform's project management layer also distinguishes between internal review and external routing, documenting concepts like Project Management roles, Editor/LSP hierarchy, agencies, and dubbing studios, which means the review gate is a structural point where your own LSP relationships can plug in if your governance model requires it.

This is the architectural shift to note: quality gating is a field you set at order-creation time, adjustable order by order, language by language.

Stage 4: Move from polling to webhook-driven callbacks

Every team's first working integration polls. It's the fastest thing to build: create the order, then loop a status check until it reports done. Ollang's agent-facing workflow documents this as a starting pattern, upload the file, create the order, then monitor status by polling until it reports completed. This is fine for a prototype. It is the wrong architecture for production, where polling means wasted requests, delayed pipeline triggers, and rate-limit pressure at scale.

The production path is a callback. Ollang's API surface documents webhooks as a first-class capability alongside orders and QC, programmatic uploads, orders, projects, revisions, QC, human review, and webhooks are all API-key authenticated. You can see the pattern in the QC evaluation endpoint, where a request accepts a callbackUrl parameter and returns immediately with a message confirming the evaluation started and that you'll be notified when it's completed rather than blocking the caller. The same asynchronous-notification pattern applies across long-running operations, uploads, dubbing renders, human review completion, which is the class of work that should not sit inside a synchronous polling loop.

Migrating to webhooks is where engineering should expect to spend real integration time, since it touches your own infrastructure, not just Ollang's. The troubleshooting reference groups this explicitly as one of the standard integration categories: most integration issues fall into a handful of buckets, authentication, uploads, callbacks, order state, or rate limits, and that page is worth reading before opening a support ticket.

Stage 5: Retries, error handling, and folder structure for scale

The last stage is the one that separates a working proof of concept from something that survives production traffic. Three things matter here: rate limits and backoff, timeouts on long operations, and folder structure as an organizational contract.

Rate limits and backoff. Ollang enforces per-account rate limits, and the documented handling pattern is standard exponential backoff: if you receive a 429, back off exponentially and retry. For high-volume use cases, contact Ollang to discuss limits before launch. Build this into your client library once, at the transport layer, rather than re-implementing it per call site.

Timeouts on long operations. Large uploads and format conversions are not instant, and your HTTP client needs to reflect that. Some operations, large uploads and AE conversions, intentionally take minutes, so increase your HTTP client's read and write timeouts to 5 to 10 minutes for uploads and avoid reusing a connection across unrelated requests. Certain formats have their own resilience path already built in, Adobe After Effects ZIP uploads run through a retry-with-backoff path with a 5-minute conversion timeout, but your client-side timeout settings still need to accommodate that window.

Folder structure as organizational contract. At ticket-queue scale, "where does this file live" was solved by a shared drive folder and a naming convention someone remembered. At API scale, it has to be explicit. Ollang's data model is a Folder → Project → Order hierarchy, and if you don't specify where content lands, it lands in a default bucket you'll have to sort later: pass the destination folderId on the upload request, because without it, projects land in the default API Uploads folder. For teams migrating multiple product lines or business units onto the same API key, deciding your folder taxonomy before you script bulk uploads saves a painful reorganization later. You can list existing folders programmatically with the Retrieve All Folders endpoint, use it to confirm your naming convention lines up with what's actually in the system before you scale ingestion.

The argument for staging it this way

None of these five stages requires the others to be finished first. A team can run Stage 1 and 2 in a sprint, keep humans in the loop for order creation for another quarter, and only tackle webhooks once volume justifies it. That is the point. Legacy localization vendors sell relationships that resist incremental change, a new workflow means a new SOW, a new onboarding call, a new set of forms. An execution layer accessed through documented endpoints does not have that friction, because each stage of the migration is an API you call, gated by decisions you already control: which folder, which review level, which callback.

The underlying shift is this: localization becomes infrastructure your systems depend on continuously, invoked by CI on every content push, by a CMS on every publish, eventually by an agent deciding on its own that a document needs a target-language version before it can complete its task. Full reference for every endpoint in this playbook, including request and response schemas, is maintained at Ollang's API documentation, the place to verify implementation details as you move from stage to stage rather than treating this playbook as the final word on any single call.