Assignar Pay API

The Assignar Pay API lets your own systems read and update your organization's data: pay results, timesheets, cost codes, invoices, purchase orders and more. It is a JSON REST API authenticated with API keys that an Owner or Admin creates in Settings.

These pages cover getting started. For every endpoint's parameters, request body and response fields, use the API reference.

Before you start

• An API key for your organization. An Owner or Admin creates one in Settings → API Keys and chooses what it may reach. See Manage API keys.
• The key's scopes must cover the endpoints you call. See Scopes and endpoints below.

A key belongs to one organization. Every request made with it reads and writes that organization's data only, so you never pass an organization ID.

Base URL

https://pay.assignar.com/api/v1

Every path in these pages and in the reference is relative to it, for example https://pay.assignar.com/api/v1/timesheets.

Authenticate

Send the key in the X-API-KEY header:

curl "https://pay.assignar.com/api/v1/cost-codes?page_size=10" \
  -H "X-API-KEY: sk_your_api_key"

You can send it as a bearer token instead: Authorization: Bearer sk_your_api_key. If a request carries both headers, the X-API-KEY value is used.

A request with no key, or with a key that is wrong, revoked or expired, gets 401:

Make your first request

List your cost codes. Any key with the Reference Data scope can do this:

curl "https://pay.assignar.com/api/v1/cost-codes?page=1&page_size=2" \
  -H "X-API-KEY: sk_your_api_key"

{
  "data": [
    {
      "id": "96a1c596-83aa-43f8-a719-fa872b5238e4",
      "code": "AL-LOAD",
      "description": "Annual Leave Loading 17.5%",
      "default_unit": "hours",
      "default_unit_price": 0,
      "code_type": "payitem",
      "is_active": true,
      "category": { "id": "1756649c-…", "name": "General" },
      "subcategory": { "id": "f05f5cab-…", "name": "General Subcategory" },
      "created_at": "2026-09-25T22:09:16.317156+00:00",
      "updated_at": "2026-09-25T22:09:16.317156+00:00"
    }
  ],
  "pagination": { "page": 1, "page_size": 2, "total": 74, "total_pages": 37 }
}

(Some fields are left out here.) Lists come back as data plus pagination, a single record as data alone, and an error as error. Paging, filtering, sorting, rate limits and every error code are on Requests and errors.

Scopes and endpoints

A key carries one or more scopes. Each scope pairs a Resource Type with an Action, written resource:action, for example payroll:read:

• Read (read) allows the GET endpoints of that resource type.
• Write (Create, Update, Delete) (write) allows its POST, PATCH and DELETE endpoints, and its GET endpoints too.
• All Actions (*) allows everything on that resource type.

The resource types, and the endpoints an API key can call with them:

Write on Resources is what adds, changes and archives workers and employment types; Write on Payroll can't. Write on Accounting is what creates clients.

A call outside the key's scopes gets 403 with the scope it needs, for example {"error": "Insufficient scope: requires reference_data:write"}. Scopes decide which endpoints you can call, not which fields you get back: a timesheet includes its client's and project's names, which are Accounting data, when the key holds only a Payroll scope.

What an API key cannot do

The reference also lists endpoints that answer only to an Assignar Connect workspace, because they act as a person in your organization rather than as a key. Called with an API key, each one returns 403:

• Creating a purchase order (POST /purchase-orders), creating or updating an order (POST /orders, PATCH /orders/{id}), assigning a Business Unit (POST /business-unit-assignments), importing a supplier invoice (POST /supplier-invoice-imports, POST /supplier-invoice-imports/uploads), importing a supplier quote as a draft purchase order (POST /supplier-quote-imports, POST /supplier-quote-imports/uploads), and adding or removing a worker's tags. The 403 body explains that the action needs a Connect workspace connection.
• Financial exception decisions and revocations (POST /client-financial-controls/exceptions/{id}/decide and /revoke). These require a Connect workspace acting as a person who currently has the approval or override permission for that exception.
• The tax-rate and team-member lists (GET /tax-rates, GET /members).
• Quote PDF downloads (GET /quotes/{id}/pdf). See Get quote contacts and a PDF through Connect.
• Forms, form submissions, workpacks, defects, SMS, notifications, approvals and webhook subscriptions. The key form offers no scope for these, so a key always gets Insufficient scope.

To automate across these, build the workflow in Assignar Connect instead.

Get quote contacts and a PDF through Connect

To attach a quote to an email sent from your own mailbox, use an Assignar Connect workspace connection. Your organization needs Quoting, and the connection's acting user needs quotes.view. Downloading the PDF also requires finance.sell.view; reading the quote's contacts requires clients.view.

1. Call GET /quotes/{id} with the quote's UUID. The response's data.contacts lists the client contacts attached to that quote, with the primary contact first and deleted contacts left out.
2. Call GET /quotes/{id}/pdf. It renders the quote using the print template assigned to it and returns JSON with data.quote_id, filename, content_type, url and expires_at. The content_type is application/pdf.
3. Download the file from data.url and attach it to your email. The signed link expires after 15 minutes; data.expires_at gives the expiry time in ISO 8601 format. Request another PDF link if it expires before you download the file.

Each contact includes id, name, first_name, last_name, email, phone and is_primary. An absent email address or phone number is null. An empty contacts array means there are no available contacts on the quote.

If the acting user lacks clients.view, or you use an ordinary API key, data.contacts is null and the response's top-level redacted_fields includes contacts. Treat this as withheld contact information, not as an empty recipient list. Contacts are included only on the quote detail endpoint, not on GET /quotes.

Each PDF request renders again. Allow time for rendering before the JSON response arrives. The endpoint uses the assigned template without a template override parameter.

Import a supplier quote through Connect

Use a Connect workspace connection running as a person who can create purchase orders. The organization must include Procurement. The import reads the document for a person to review in Pay; it does not create or approve a purchase order.

1. Send POST /supplier-quote-imports/uploads with file_name. Keep the returned data.import_id, storage_path, token and signed_url.
2. Upload the file bytes to signed_url using the returned token. Use a PDF or PNG, JPEG or WebP image up to 25 MB, or a CSV or XLSX file up to 10 MB. HEIC and HEIF files can be uploaded but cannot be read; convert them before uploading.
3. Send POST /supplier-quote-imports with import_id, storage_path and file_name. Include an Idempotency-Key that identifies the source file, such as a mailbox message ID plus attachment ID, or a drive file ID plus revision. After a timeout, retry with the same key and body rather than uploading again.
4. Poll GET /supplier-quote-imports/{id}. When status is needs_review, a person checks the quote in Pay and creates the purchase order. When it is committed, created_purchase_order_id identifies the purchase order; for failed, read error_message before trying again.

A 201 from step 3 means the import was accepted, not that a purchase order was created. A repeat request returns 200 with the existing import.

XLSX workbooks can have up to 20 non-empty sheets, 2,000 data rows across those sheets and 60 columns per sheet. Spreadsheets must fit within 40,000 characters of cell text.

If reading a PDF fails with a 20-page-limit error, split it into smaller PDFs and upload each separately with its own source identity. The API reference lists the request and response fields.

To review the document, correct prices and create the purchase order, the reviewer also needs access to cost figures. See Raise purchase orders.

Sync financial assessments

Read GET /client-financial-controls/capabilities to build commercial-action and policy selectors. It returns data.actions and data.policies, each an array of {value, label} choices, without reading an organization's settings, statuses or assessments. It accepts a read scope for client_financial_assessments, client_financial_policies, accounting or operations.

Read GET /client-financial-controls for the organization's own statuses and settings. Use the returned status IDs when writing assessments or updating statuses; renaming a status preserves its ID. Access to capabilities does not grant access to this private configuration.

Use PUT /clients/{id}/financial-assessment to record a manual assessment or import one from an accounting system. For an import, send expectedVersion and an assessment with sourceKind: "integration", sourceName, observedAt, statusId and reason. You can include sourceReference, creditLimit, exposure and currency. Send money as decimal strings, such as "1000.25"; leave amounts out to keep their current values.

Read the assessment first and use its version as expectedVersion, or 0 for a new assessment. A concurrent change or an import older than the current assessment returns 409 with code: "conflict". After a conflict, read the current state and prepare a new change. Use the source's actual observation time; a successful retry must not make old data look newly observed.

Manual assessments default to manualLock: true, which prevents an integration from replacing them. Release the lock with a manual update and a reason before resuming integration updates.

Financial controls start switched off for every organization. Importing an assessment or creating a status leaves that setting unchanged. Enable enforcement explicitly through PUT /client-financial-controls/settings; use the returned settings revision for subsequent changes. Private assessment details require the financial assessment scope, while withheld amounts return null with redactedFields.

To check an action, send clientId and action to POST /client-financial-controls/evaluate. It returns inactive, allowed, warned, approval_required or blocked. This is a client-level policy decision; the evaluation body does not accept a job or order context.

For an exception request, send clientId, action, a stable requestKey UUID and a request containing the reason and the returned assessmentVersion, policyRevision and settingsRevision to POST /client-financial-controls/exceptions. Include request.orderId to scope it to an existing order belonging to the client. Poll /client-financial-controls/exceptions/{id} for its safe status, expiry and consumption state; the full history needs financial assessment read access.

In Connect, pass the exception ID as financial_exception_id when registering the human review through POST /approvals. The request must belong to the same requesting person or key, and the nominated reviewer needs the current financial approval or override permission. An ordinary approval without this link does not authorize a financial exception; the commercial action still validates the current exception when it runs.

Financial writes accept Idempotency-Key. After a timeout, retry with the same key and exact body. A replay reads the result through your current access, so a changed visibility grant can change the returned fields; after reviewing a version conflict, a new change needs a new key. The API reference lists every action, policy, request field and response shape.

Connect's native financial steps use the workspace acting user's effective permissions. Existing account-wide keys do not gain financial scopes automatically; private assessment and configuration calls still require the appropriate explicit financial scope.

Link an approval to a record

POST /approvals can link the approval to a record with record.entity_type and record.entity_id. The connection's acting user must be able to see that record, including when your organization limits access by location. A record they can't see, or one that doesn't exist, returns 404 with Record not found, and no approval is created. Use a connection whose acting user can see the record, or check the ID.

Create and manage projects

Reading a project needs Accounting / Read or Payroll / Read. Creating, changing, deleting and restoring one needs Accounting / Write (Create, Update, Delete).

Read projects

GET /projects is the pick list for dropdowns: an id and label for each project. For whole records use GET /projects/{id}, or GET /projects/list, which is paginated and takes filters such as status=eq.Active, client_id=eq.<uuid>, external_id=eq.ACU-1001 and datasource=eq.public_api. Add search to match the name or code, and updated_since (an ISO 8601 timestamp with its time zone, such as 2026-10-01T00:00:00Z) to fetch only projects changed since your last sync.

A project includes its name, code, client (id, name, external_id), status, region, description, start_date, estimated_end_date, actual_end_date, its tags, external_id, datasource and timestamps. Deleted projects are left out of every list, and GET /projects/{id} returns 404 for them.

Create a project

Every project belongs to a client, so create or find the client first, then create the project with the client's id or its external_id:

# Accounting / Write (Create, Update, Delete)
curl -X POST "https://pay.assignar.com/api/v1/clients" \
  -H "X-API-KEY: sk_your_api_key" \
  -H "Idempotency-Key: client-C-9" \
  -H "Content-Type: application/json" \
  -d '{"name": "Harbourside Developments", "external_id": "C-9"}'

curl -X POST "https://pay.assignar.com/api/v1/projects" \
  -H "X-API-KEY: sk_your_api_key" \
  -H "Idempotency-Key: project-ACU-1001" \
  -H "Content-Type: application/json" \
  -d '{"name": "Harbour Bridge Repaint", "code": "HBR-01", "client_external_id": "C-9", "status": "Active", "start_date": "2026-11-02", "external_id": "ACU-1001"}'

Send exactly one of client_id and client_external_id. The client must be an active client in your organization, otherwise the request returns 422. You can't move a project to another client afterwards. status is Planning (the default), Active, On Hold or Completed, and dates are YYYY-MM-DD. The response is 201 with the new project, which has datasource set to public_api.

Customers whose portal access covers the whole client see its new projects there too.

Send the same project again

If you send an external_id and a project you created through the API already has it, you get 200 with that project and nothing is changed. 201 means a project was created. This makes a sync safe to re-run: send the same project again and you get the same record back. To retry a request that timed out, also send the same Idempotency-Key (see Retry a write safely).

Change, close out or remove a project

• Change details with PATCH /projects/{id}. Send only the fields you are changing; null clears one. The response is the updated project.
• Close out a finished job by setting status to Completed. The project stays visible, with its history.
• Remove a project created by mistake with DELETE /projects/{id}. It disappears from lists and lookups, and nothing linked to it is removed. The response is the deleted project. Bring it back with POST /projects/{id}/restore.

Projects from Assignar Ops

Projects synced from Assignar Ops have datasource set to assignar. You can change them, but while your organization is connected to Ops, the next sync overwrites their name, client, status, description, start_date and estimated_end_date, and their Business Unit when Ops sends one. An Ops project's code and external_id can't be changed.

A project your principal contractor manages through the Subcontractor Hub keeps the name, code and status they give it.

When a request is refused

A refused write comes back as {"error": "…", "code": "…"}. A key without the scope gets 403 with Insufficient scope: requires accounting:… and no code.

Through Assignar Connect

A Connect workspace connection works as its acting user. Creating a project needs that person to hold Create projects, and changing one needs Update projects. Deleting or restoring needs Delete projects as well. An older account-wide Connect key can create and change projects but can't delete or restore them.

Assign a Business Unit by code

POST /clients takes a business_unit_code. So do POST /orders and PATCH /orders/{id}, which need an Assignar Connect workspace connection. Codes match without regard to capital letters, but leading zeros matter: 007 and 7 are different codes. The code must belong to your organization.

Leave the field out to keep an existing assignment. Send null to clear it. An archived Business Unit can stay on a record that already has it, but you can't assign it to another record.

To assign or clear a Business Unit on an existing client, project, order, worker or asset, send POST /business-unit-assignments:

{
  "entity_type": "project",
  "record_id": "00000000-0000-4000-8000-000000000001",
  "business_unit_code": "007"
}

entity_type is one of client, project, order, worker or asset, and record_id is the record's UUID. A successful response returns data with entity_type, record_id, business_unit_id and business_unit_code.

This endpoint answers only to a Connect workspace connection running as a Pay user who can update that type of record; an API key gets 403. An unknown code, or an archived one you try to assign, returns 422: choose an active code from your list. A record that doesn't exist or that the user can't reach returns 404. A code sent here is an explicit assignment, not a location default. Your Business Units and their codes are listed in Manage Business Units.

Archive and restore clients

Archive a client with DELETE /clients/{id}. The client is hidden, not erased: it no longer appears in GET /clients or GET /clients/{id}, and Assignar Pay treats it as deleted, the same as deleting a client in the app. The API has no permanent delete. POST /clients/{id}/restore brings an archived client back.

Both endpoints need a key whose Accounting scope has the action Write (Create, Update, Delete) or All Actions. A key with Read gets 403. In Assignar Connect, a workspace connection can call them when its acting user has clients.delete.

curl -X DELETE "https://pay.assignar.com/api/v1/clients/4bed9933-2c1d-4f5e-8a6b-7c8d9e0f1a2b" \
  -H "X-API-KEY: sk_your_api_key" \
  -H "Idempotency-Key: archive-4bed9933"

{
  "data": {
    "id": "4bed9933-2c1d-4f5e-8a6b-7c8d9e0f1a2b",
    "name": "Harbourside Developments",
    "external_id": "xero-1042",
    "datasource": "public_api",
    "is_deleted": true,
    "updated_at": "2026-10-20T05:00:00.000000+00:00"
  }
}

(Some fields are left out here.) The response is the same client record GET /clients/{id} returns. To undo it:

curl -X POST "https://pay.assignar.com/api/v1/clients/4bed9933-2c1d-4f5e-8a6b-7c8d9e0f1a2b/restore" \
  -H "X-API-KEY: sk_your_api_key" \
  -H "Idempotency-Key: restore-4bed9933"

Archiving leaves the client's projects, invoices, quotes and orders as they are. You can archive a client that still has open projects or unpaid invoices; those records stay linked to it.

When a request is refused, the response's code says why:

A retry with the same Idempotency-Key replays a successful archive or restore. A refused request isn't kept against its key, so once you've fixed the cause you can retry with the same key.

Each call counts toward your key's rate limits. A script that archives many clients should pace its requests and retry a 429 after the Retry-After delay.

If your organization syncs clients from Assignar Ops, archive the client in Ops as well. Archiving here doesn't change Ops. When a later sync brings the client from Ops again, it usually creates a new copy with the same external_id; a docket sync restores the archived client instead. Once a new copy exists, restoring the archived client returns 409 with external_id_conflict.

Import competencies from Assignar Ops

Three endpoints move your competency catalogue, your workers' credentials and their evidence files from Assignar Ops into Pay. The key needs Reference Data / Write (Create, Update, Delete) for step 1, and Payroll / Write (Create, Update, Delete) for steps 2 and 3.

Each request takes up to 100 items. Each replies 200 with a results list (one entry per item you sent, in the same order, each with its index and external_id) and a summary that counts the items per status. One item failing never stops the others. A request refused for missing permission gets 403; one with more than 100 items or a malformed body gets 400. All three accept an Idempotency-Key header (see Retry a write safely).

Run the import

1. Import the catalogue. Send POST /competencies/import with items. Each item needs the Ops competency id as external_id and a name. It can also carry description, requires_expiry_date, requires_issue_date, requires_attachment, requires_verification and alert_lead_days (0 to 365).

   To import a site induction, also send kind as induction and exactly one of client_external_id or project_external_id: the Ops id of a client or project you've already brought into Pay. Pay creates the induction for that client or project. An induction always records the completion date (issued_at in step 3) and has no expiry requirement, so the item's requires_issue_date and requires_expiry_date are ignored. Leave kind out, or send ticket, for every other competency.

2. Request upload slots for the credentials that have files. Send POST /worker-competencies/evidence-uploads with one item per file:

   • credential_external_id: the Ops credential id the file belongs to (the same id you send as external_id in step 3)
   • the worker, as worker_external_id (the worker's Ops user id) or employee_id
   • the competency, as competency_external_id or competency_id
   • file_name, and optionally content_type and file_size

   Pay first checks the credential the way step 3 will. If it was already imported, would be skipped, or its worker or competency isn't in Pay, you get that status and no slot, so you don't download files Pay won't use. Each ready result gives an upload_id and a signed_url. PUT the original file bytes to that URL with Content-Type set to the file's type. A slot works for about two hours, and Ops download links expire at about the same time, so upload each file as soon as you have fetched it.

3. Import the credentials. Send POST /worker-competencies/import. Each item needs the Ops credential id as external_id, the worker (worker_external_id or employee_id), the competency (competency_external_id or competency_id) and has_source_evidence. It can also carry license_number, issuer, issued_at, expiry_at (both as YYYY-MM-DD), notes, status (active or archived) and up to 20 evidence entries, each with an upload_id and an optional label.

Files can be any type Ops holds, up to 50 MB each; empty files are refused. An uploaded file that no imported credential uses within 24 hours is deleted, so request fresh slots if you import a page later than that.

Read the results

Upload slots (step 2):

Catalogue items (step 1):

Credentials (step 3):

An item that comes back evidence_missing, requirement_missing, evidence_invalid or rejected saves nothing, so you can fix it and resend without cleaning up.

Things to know

• You can re-run any step. Items already in Pay come back already_imported, so an import that stopped halfway finishes without duplicates. Two different Ops credentials for the same worker and competency are both imported.
• Workers must have come from Assignar Ops. A worker added by hand, from a CSV file or through another API has no Ops id and returns worker_not_mapped. If you already hold the worker's Pay id, send employee_id instead.
• Imported credentials are never marked verified. They follow the competency's requires_verification setting: credentials for a competency that requires verification start as pending verification, and the rest need none. Each created result shows the credential's verification_state.
• Read credentials back with GET /worker-competencies (Payroll / Read), which filters on external_id, employee_id, worker_external_id and competency_id. GET /worker-competencies/{id}/evidence returns each file with a signed_url that works for 5 minutes. Evidence for sensitive competencies is never returned to an API key.

Create and maintain workers

An HR or payroll system can keep your workers in step with Assignar Pay. The key needs Resources / Write (Create, Update, Delete). A Payroll key can read workers but can't add or change them.

Fields you can send

first_name and last_name (both required when you create a worker), email, employee_id (your worker or payroll number), employment_type_id (an id from GET /employment-types) and external_id (your system's id for the worker).

Anything else is refused with 400, and the error names the field. That includes phone, address, emergency contact, superannuation and tax details, roles, tags and datasource, so you never believe something was stored when it wasn't. Adding a worker doesn't invite them or give them a login; do that in Assignar Pay.

Create a worker

# Requires Resources / Write
curl -X POST "https://pay.assignar.com/api/v1/employees" \
  -H "X-API-KEY: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: eh-import-2026-11-02-1001" \
  -d '{
    "first_name": "Sam",
    "last_name": "Taylor",
    "email": "sam.taylor@example.com",
    "employee_id": "1001",
    "employment_type_id": "219376c6-f0c3-4ff8-87d0-93505f22fdce",
    "external_id": "EH-1001"
  }'

The response is the worker, with datasource set to public_api.

Sending the same worker again

Two things stop a repeat send from creating a second worker:

• Idempotency-Key header. If a request times out and you retry it with the same key and the same body, you get the first response back and nothing runs twice. Use one key per request you mean to make.
• external_id. If you POST a worker whose external_id matches a worker you already created through the API, you get that worker back with 200 instead of 201, unchanged, and no new worker. To change their details, use PATCH.

Your external_id only matches workers created through the API. Workers synced from Assignar Operations keep their own Ops ids, even when a value happens to be the same.

POST /clients works the same way for clients: a client that already has the external_id you send comes back with 200, unchanged.

When a worker write is refused

Workers synced from Assignar Operations

If your organization syncs workers from Assignar Operations, those workers have datasource set to assignar. You can update them, but Operations stays in charge: the next sync that includes the worker puts back their name, email, worker number and employment type from Operations. Make lasting changes to these workers in Assignar Operations.

Archive and restore

DELETE /employees/{id} archives a worker: they stop appearing in GET /employees and GET /employees/{id}, and the response shows is_deleted: true. Archiving through the API doesn't remove the worker's login or their access to your organization, so POST /employees/{id}/restore brings them back exactly as they were. To remove access, do it in Assignar Pay.

# Requires Resources / Write
curl -X DELETE "https://pay.assignar.com/api/v1/employees/2a6b0035-bd73-4d5b-a525-fe3ca8a3a29c" \
  -H "X-API-KEY: sk_your_api_key"

Archiving a worker who is already archived, or one that doesn't exist, returns 404. Restoring a worker who isn't archived returns 409 with code not_archived. Restoring one whose worker number, external_id or login another worker has since taken returns 409 too, with code duplicate_employee_id, duplicate_external_id or duplicate_login.

If your system re-hires someone you archived, restore their worker rather than adding them again. A POST with an archived worker's external_id is refused with archived_external_id and names the worker to restore.

Archive workers synced from Assignar Operations in Operations as well. If Operations sends the worker again, the next sync adds them as a new worker rather than restoring the archived one.

Tags and employment types

Adding or removing a worker's tags needs an Assignar Connect workspace connection; an API key can't do it. Employment types are under Resources too: list them with GET /employment-types, and add or rename them with POST /employment-types and PATCH /employment-types/{id}.

Use the API reference

The API reference lists every endpoint, grouped by resource, with its query parameters, request body, response fields and error responses. Open an endpoint to read its schema.

To send requests from the page, click Authorize, paste your key into Value under ApiKeyAuth, and click Authorize. Then open an endpoint, fill in its parameters and click Execute. These are real calls against your organization's data, so take care with write endpoints. The page remembers the key in your browser until you click Authorize and Logout.