Full Integration Workflow

​

At a glance

1. Authentication and token refresh
2. Import (project/job creation)
3. Monitoring (webhook-first)
4. Export and DELIVERED status
5. Optional extensions and hardening

​

Prerequisites

• Completed Quick Start.
• Phrase TMS project template(s) aligned to your workflow.
• Platform and TMS API base URLs for your tenant/region.
• Secure storage for API token and runtime secrets.
• A callback/webhook endpoint if you use push-based progress handling.

​

1) Authentication strategy

• Base flow: POST ${PLATFORM_BASE_URL}/idm/oauth/token (token exchange).
• Include Authorization: Bearer <access_token> on API requests.
• Refresh on expiry and on a single retry after 401.

• Platform authentication
• OAuth token endpoint

​

2) Import content into TMS

​

Required path

1. List templates: GET /api2/v1/projectTemplates
2. Create project: POST /api2/v2/projects/applyTemplate/{templateUid}
3. Create jobs: POST /api2/v1/projects/{projectUid}/jobs

​

Live preview integration point (optional)

1. Upload a preview package after project creation.
2. Store the returned preview package file UID.
3. Include jobPreviewPackageFileUidRef when creating the job.

​

Optional path: expose content listing/download endpoints

• Expose a list endpoint to return selectable content.
• Expose a download endpoint to return encoded content for import.
• Validate auth and return clear HTTP errors for invalid requests.

• List project templates
• Create project from template
• Create job

​

Optional workflow extensions

• Assign providers from template: POST /api2/v1/projects/{projectUid}/applyTemplate/{templateUid}/assignProviders
• Create analyses by providers: POST /api2/v1/analyses/byProviders
• Notify assigned users: POST /api2/v1/projects/{projectUid}/jobs/notifyAssigned

• Assign providers from template
• Create analyses by providers
• Notify assigned users

​

3) Monitor job progress

1. Webhooks (recommended for production)
2. Async request status polling
3. Job-part polling fallback

​

Webhooks

• Configure webhook subscriptions for job/part/async lifecycle events.
• Verify sender token/header.
• Store events idempotently, acknowledge quickly, and process asynchronously.

​

Async status

• Poll GET /api2/v1/async/{asyncRequestId} for completion when the workflow uses async endpoints.

​

Callback pattern (alternative to polling)

• Callback payload includes async request metadata and action result.
• Callback endpoint should validate sender, persist event, and return 200 quickly.
• If callback URL is unreachable, Phrase retries after 2, 4, 8, 16, and 30 minutes (up to 10 failed retries).
• Callback delivery is considered successful only when your endpoint returns HTTP 200.

POST /callbacks/phrase-async
  verifySignatureOrToken(request)
  event = parseJson(request.body)
  saveEventIdempotently(event.asyncRequest.id)
  enqueueAsyncProcessing(event)
  return 200

​

Job-part status fallback

• Poll GET /api2/v1/projects/{projectUid}/jobs/{jobUid}/parts with backoff and jitter.

• Get asynchronous request
• Job parts endpoint: GET /api2/v1/projects/{projectUid}/jobs/{jobUid}/parts
• Webhooks (support article)

​

Job status reference

​

4) Export translated content

​

Pull from TMS via API

1. Start async export: PUT /api2/v3/projects/{projectUid}/jobs/{jobUid}/targetFile
2. Wait for completion via webhook/callback/polling.
3. Download file once ready: GET /api2/v2/projects/{projectUid}/jobs/{jobUid}/downloadTargetFile/{asyncRequestId}
4. Import result into third-party system.
5. Set terminal status: POST /api2/v1/projects/{projectUid}/jobs/{jobUid}/setStatus with DELIVERED.

​

Push from TMS to your plugin (optional)

• Download target file async
• Download target file by async request
• Edit job status

​

5) Continuous updates (optional, high-change workflows)

• Use POST /api2/v1/projects/{projectUid}/jobs/source
• Monitor completion using callbacks, webhooks, or async polling.
• Re-export translated output when updates finish.

• Update source

​

6) Metadata and reporting

{
  "sourceData": {
    "clientType": "MY_PLUGIN",
    "clientVersion": "1.2.4",
    "hostVersion": "4.5.2"
  }
}

• clientType is required and must be registered with Phrase.
• clientVersion and hostVersion are optional.

​

7) Idempotency implementation guidance

1. Build deterministic operation key before API call.
2. Check/store key in durable storage with operation state.
3. If duplicate key appears, return previously stored result instead of replaying.

​

8) Logging field specification

​

Plugin variants

​

Operational hardening checklist

• Retry transient errors (429, 5xx) with exponential backoff + jitter.
• Avoid duplicate create/export actions with idempotency keys or dedupe logic.
• Log correlation IDs, project/job IDs, endpoint, status, and latency.
• Track success rates and error rates for create/monitor/export operations.
• Add alerts for repeated failures and webhook delivery issues.

​

Testing expectations

• Happy path: create → monitor → export → DELIVERED.
• Failure path: auth errors, validation errors, rate limits, service errors.
• Resilience path: webhook miss + polling fallback.
• Update path (if enabled): source updates and repeated export.

​

Optional reference: payloads and endpoint map

​

Core payload snippets

{
  "name": "Website Translation",
  "sourceLang": "en",
  "targetLangs": ["de", "fr"]
}

{
  "uid": "proj-uid-1",
  "name": "Website Translation",
  "status": "NEW",
  "sourceLang": "en",
  "targetLangs": ["de", "fr"]
}

{
  "jobs": [
    {
      "uid": "job-uid-1",
      "status": "NEW",
      "targetLang": "de"
    }
  ],
  "asyncRequest": {
    "id": "async-req-1",
    "action": "PRE_ANALYSE"
  }
}

{
  "requestedStatus": "DELIVERED",
  "notifyOwner": true,
  "propagateStatus": true
}

​

Endpoint reference glossary

​

Additional resources

• Postman collection for rapid API validation and manual flow testing.
• TMS API reference for full payload schemas.
• Webhooks support guide for account-level event setup and retries.

​

Next steps