Async operations

Singular Asynchronous Requests

To make a singular asynchronous request, append /async at the end of the respective synchronous POST endpoint. For asynchronous requests, the server returns a task_id, a unique identifier used to track the status of the async operation.

Endpoint

POST /<common_model>/async

Sample response

1
{
2
    "task_id": "dc27d1b7-6627-4f2e-8b0e-0439f76642ff"
3
}

To check the progress and get the final result, send a request to the task polling endpoint:

GET https://api.merge.dev/api/accounting/async-tasks/{task_id}.

Bulk Asynchronous Requests

For high-volume write operations, certain Common Models support the Bulk POST feature, which allows you to create or update multiple objects in a single API call rather than making separate requests for each one. Use this instead of singular async requests when you need to write many objects at once — it minimizes API overhead and helps you stay within third-party rate limits.

Integration support

The bulk write endpoint currently supports the following integrations and Common Models. If you have specific Common Models or integrations you’d like to see coverage for, please let us know by reaching out to your CSM or support@merge.dev!

Endpoint

POST /<common_model>/bulk

Sample request body

The request body must adhere to the following requirements:

• Max payload size of 5 MB or 100 objects
• Each object must contain a unique item_id that maps to the item’s ID in the third-party system
• Each object should be identical in structure to the payload used in the single-object POST endpoint for the corresponding Common Model

1
{
2
    "batch_items": [
3
        {
4
            "item_id": "1",
5
            "payload": {
6
              "type": "ACCOUNTS_RECEIVABLE",
7
              "contact": "022a2bef-57e5-4def-8ed2-7c41bd9a5ed8",
8
              "number": "AIQ12546",
9
              "issue_date": "2020-03-31T00:00:00Z",
10
              "due_date": "2020-04-15T00:00:00Z",
11
              "paid_on_date": "2020-04-01T00:00:00Z",
12
              "memo": "Weekly Payment",
13
              "company": "595c8f97-2ac4-45b7-b000-41bdf43240b5",
14
              "employee": "7442f0d5-722d-45bd-b807-6e38489d37fe",
15
              "currency": "USD",
16
              "exchange_rate": "2.9",
17
              "payment_term": "89d329de-825f-4ac6-8369-3c58b4e68bee",
18
              "total_discount": 0,
19
              "sub_total": 100,
20
              "status": "DRAFT",
21
              "total_tax_amount": 5,
22
              "total_amount": 105,
23
              "balance": 105,
24
              "tracking_categories": [
25
                "7dc5ca17-d311-44cd-9ce0-333080367a18"
26
              ],
27
              "accounting_period": "7dc5ca17-d311-44cd-9ce0-333080367a18",
28
              "line_items": [
29
                {
30
                  "description": "Pickleball lessons",
31
                  "unit_price": 50,
32
                  "quantity": 1,
33
                  "total_amount": 50,
34
                  "currency": "USD",
35
                  "exchange_rate": "2.9",
36
                  "employee": "7442f0d5-722d-45bd-b807-6e38489d37fe",
37
                  "tax_rate": "a12e7c20-1922-9df7-s75n-edfeewnn7384",
38
                  "item": "5b3c1341-a20f-4e51-b72c-f3830a16c97b",
39
                  "account": "cd0f32d4-a493-11ec-b909-0242ac120002",
40
                  "project": "22e65a5d-2df5-4e6e-884a-e538d0339000",
41
                  "contact": "908934-49j9-093f-0989-908923908",
42
                  "tracking_categories": [
43
                    "b38c59b0-a9d7-4740-b1ee-5436c6751e3d"
44
                  ],
45
                  "company": "595c8f97-2ac4-45b7-b000-41bdf43240b5"
46
                }
47
              ],
48
              "inclusive_of_tax": true
49
            }
50
        }
51
    ]
52
}

Sample response

1
{
2
    "batch_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
3
}

To check the status or error messages returned from the 3rd party integration, utilize the batch polling endpoint:

GET /<common_model>/bulk/{batch_id}

Sample polling response

1
{
2
  "batch_id": "123e4567-e89b-12d3-a456-426614174000",
3
  "status": "PARTIAL_SUCCESS",
4
  "total_count": 2,
5
  "objects": [
6
    {
7
      "item_id": "1",
8
      "status": "SUCCESS",
9
      "response": {
10
        "merge_common_model_id": "9871b4a9-f5d2-4f3b-a66b-dfedbed42c46"
11
      }
12
    },
13
    {
14
      "item_id": "2",
15
      "status": "FAILED",
16
      "response": {
17
        "error_message": "You cannot update this invoice at this time"
18
      }
19
    }
20
  ]
21
}

Possible overall statuses

• ENQUEUED - The request has been received and a task has been enqueued for processing
• IN_PROGRESS - The enqueued task is being processed
• PARTIAL_SUCCESS - The task has been processed, but not all objects were written successfully
• SUCCESS - The task has been processed, and all objects were written successfully
• FAILED - The task has been processed, but ran into an error while processing
• RATE_LIMITED - The request was received but ran into rate limits while processing. Rate-limited objects are automatically retried.

Possible per-object status values

• PENDING - This object has not been processed yet
• SUCCESS - This object was successfully POSTed
• FAILURE - This object was not successfully POSTed

Integration-Specific Behavior

For integration-specific behavior, data, and best practices, visit this help center article.

Webhooks

Instead of polling the async task status endpoints, you can subscribe to webhook events that fire automatically when async operations complete:

• AsyncPost.completed — fires when a single async POST request reaches a terminal state (COMPLETED or FAILURE).
• AsyncBulkPost.completed — fires when a bulk async POST batch reaches a terminal state (SUCCESS, PARTIAL_SUCCESS, or FAILED).

For full payload examples and instructions, see Merge Webhooks.