Resume record import — Brigg developers

Access & visibility

Allow integrations.ResumeRecordImport on your API key.

Workspace access by default. Private member data requires approved member delegation through Brigg-Act-As; the key supplies permissions while private ownership and project boundaries remain enforced.

Set up authentication · Choose permissions

Request fields

Send a JSON object with the following fields. Required fields must be included; omit optional fields you do not need.

job_idstringRequired

Import job ID returned by StartRecordImport.

At least 1 character.

Track progress and recover

Poll Get record import and page through List record import rows. Row numbers refer to physical input lines, starting at 1. A completed job can include failed rows: inspect the failed count. Validation failures are recorded and skipped; source access, key revocation, quota and service failures pause the job before the unfinished row.

Each successful record and its resume position commit together. After addressing a pause, call Resume record import with a new idempotency key. A lost response to a particular control request uses that request's original key. A stopped worker can be resumed after its lease expires; a queued job can be safely dispatched again. Cancellation stops subsequent commits and retains previously saved records; cancelled jobs cannot resume.

Use the same credential and member context to inspect or control this job. Work never acquires permissions added after it started: every row intersects the original approved grant with current access. If you replace the credential, start a new job with the same external references. The permanent reference matches already imported records even after request receipts expire. Correct invalid rows in a new file, keeping those references; Brigg does not guess a match from email or name.

Response

Returns 200 OK with a JSON body.

job_idstringRequired

Stable identifier of this resumable import.

operationstringRequired

Published Upsert operation applied to every row.

file_idstringRequired

Immutable NDJSON input file.

statusstringRequired

paused requires ResumeRecordImport after the cause has been addressed. Completed imports may contain failed rows.

Allowed: "queued", "running", "completed", "paused", "cancelled".

processedintegerRequired

Rows with a retained outcome.

Minimum: 0.

createdintegerRequired

Rows whose successful upsert created a record.

Minimum: 0.

updatedintegerRequired

Rows whose successful upsert matched an existing record.

Minimum: 0.

failedintegerRequired

Invalid or refused rows; inspect ListRecordImportRows and submit corrected rows with the same external references.

Minimum: 0.

error_codestring or nullRequired

Reason the job paused, or null. Credentials, source-file access and workspace quotas are checked as the import progresses.

Errors & retries

Set BRIGG_REQUEST_ID once for each logical action. The samples send it as Idempotency-Key. Reuse the same value and body on retries, including after a timeout; a missing response does not prove the action failed.

For rate limits, follow the server’s retry guidance and back off. See HTTP errors and safe retries and limits.

HTTP status	Code	What to do
400	`invalid_json`	Send a JSON object with Content-Type: application/json.
400	`invalid_input`	Check the request fields and types. Supply a stable Idempotency-Key containing 1–200 characters.
401	`invalid_key`	The workspace API key is missing, invalid or revoked.
403	`forbidden`	Check the key’s operation and resource grants. If Brigg-Act-As is supplied, the key must be authorized to delegate to that member.
404	`not_found`	The requested operation or resource is not available to this credential.
429	`rate_limited`	Wait for Retry-After before retrying. Reuse the original Idempotency-Key.
409	`import_cancelled`	A cancelled job cannot resume. Start a new import using the same external references for records already saved.

Next steps

Download OpenAPI · Versioning & retirement

JSON schemas

Use the complete schemas for validation or client generation.

Full request JSON schema

{
  "type": "object",
  "properties": {
    "job_id": {
      "type": "string",
      "minLength": 1,
      "description": "Import job ID returned by StartRecordImport."
    }
  },
  "required": [
    "job_id"
  ],
  "additionalProperties": false,
  "examples": [
    {
      "job_id": "job_customer_sync"
    }
  ]
}

Full response JSON schema

{
  "type": "object",
  "properties": {
    "job_id": {
      "type": "string",
      "description": "Stable identifier of this resumable import."
    },
    "operation": {
      "type": "string",
      "description": "Published Upsert operation applied to every row."
    },
    "file_id": {
      "type": "string",
      "description": "Immutable NDJSON input file."
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "running",
        "completed",
        "paused",
        "cancelled"
      ],
      "description": "paused requires ResumeRecordImport after the cause has been addressed. Completed imports may contain failed rows."
    },
    "processed": {
      "type": "integer",
      "minimum": 0,
      "description": "Rows with a retained outcome."
    },
    "created": {
      "type": "integer",
      "minimum": 0,
      "description": "Rows whose successful upsert created a record."
    },
    "updated": {
      "type": "integer",
      "minimum": 0,
      "description": "Rows whose successful upsert matched an existing record."
    },
    "failed": {
      "type": "integer",
      "minimum": 0,
      "description": "Invalid or refused rows; inspect ListRecordImportRows and submit corrected rows with the same external references."
    },
    "error_code": {
      "type": [
        "string",
        "null"
      ],
      "description": "Reason the job paused, or null. Credentials, source-file access and workspace quotas are checked as the import progresses."
    }
  },
  "required": [
    "job_id",
    "operation",
    "file_id",
    "status",
    "processed",
    "created",
    "updated",
    "failed",
    "error_code"
  ],
  "additionalProperties": false,
  "examples": [
    {
      "job_id": "job_customer_sync",
      "operation": "customers.UpsertPerson",
      "file_id": "f_customers",
      "status": "queued",
      "processed": 500,
      "created": 400,
      "updated": 99,
      "failed": 1,
      "error_code": null
    }
  ]
}

Try the request

Use your API key in a server environment.

Act as a memberRequires administrator-approved delegation.

Fictional source and job IDs. Use the IDs and exact operation returned for your workspace.

Request

cURL

curl 'https://api.brigg.app/v1/operations/integrations.ResumeRecordImport' \
  -H "Authorization: Bearer $BRIGG_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $BRIGG_REQUEST_ID" \
  --data-raw '{
  "job_id": "job_customer_sync"
}'

TypeScript

const requestId = process.env.BRIGG_REQUEST_ID;
if (!requestId) throw new Error("Set BRIGG_REQUEST_ID once per action and reuse it on retries.");

const response = await fetch("https://api.brigg.app/v1/operations/integrations.ResumeRecordImport", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BRIGG_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": requestId, // Create once per action; reuse on retries.
  },
  body: JSON.stringify({
    "job_id": "job_customer_sync"
  }),
});
const result = await response.json();
if (!response.ok) throw new Error(`${response.status}: ${result.error} — ${result.message}`);
console.log(result);

Python

import json
import os
from urllib.request import Request, urlopen
from urllib.error import HTTPError

request_id = os.environ["BRIGG_REQUEST_ID"]  # Reuse for retries of this action.
payload = {
  "job_id": "job_customer_sync"
}
request = Request(
    "https://api.brigg.app/v1/operations/integrations.ResumeRecordImport",
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {os.environ['BRIGG_API_KEY']}",
        "Content-Type": "application/json",
        "Idempotency-Key": request_id,  # Create once per action; reuse on retries.
    },
    method="POST",
)
try:
    with urlopen(request) as response:
        print(json.load(response))
except HTTPError as error:
    print(error.code, json.load(error))
    raise

cURL

curl 'https://api.brigg.app/v1/operations/integrations.ResumeRecordImport' \
  -H "Authorization: Bearer $BRIGG_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Brigg-Act-As: $BRIGG_ACT_AS" \
  -H "Idempotency-Key: $BRIGG_REQUEST_ID" \
  --data-raw '{
  "job_id": "job_customer_sync"
}'

TypeScript

const actAs = process.env.BRIGG_ACT_AS;
if (!actAs) throw new Error("Set BRIGG_ACT_AS to an approved member account ID.");

const requestId = process.env.BRIGG_REQUEST_ID;
if (!requestId) throw new Error("Set BRIGG_REQUEST_ID once per action and reuse it on retries.");

const response = await fetch("https://api.brigg.app/v1/operations/integrations.ResumeRecordImport", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BRIGG_API_KEY}`,
    "Content-Type": "application/json",
    "Brigg-Act-As": actAs,
    "Idempotency-Key": requestId, // Create once per action; reuse on retries.
  },
  body: JSON.stringify({
    "job_id": "job_customer_sync"
  }),
});
const result = await response.json();
if (!response.ok) throw new Error(`${response.status}: ${result.error} — ${result.message}`);
console.log(result);

Python

import json
import os
from urllib.request import Request, urlopen
from urllib.error import HTTPError

request_id = os.environ["BRIGG_REQUEST_ID"]  # Reuse for retries of this action.
payload = {
  "job_id": "job_customer_sync"
}
request = Request(
    "https://api.brigg.app/v1/operations/integrations.ResumeRecordImport",
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {os.environ['BRIGG_API_KEY']}",
        "Content-Type": "application/json",
        "Brigg-Act-As": os.environ["BRIGG_ACT_AS"],
        "Idempotency-Key": request_id,  # Create once per action; reuse on retries.
    },
    method="POST",
)
try:
    with urlopen(request) as response:
        print(json.load(response))
except HTTPError as error:
    print(error.code, json.load(error))
    raise

200 OK Response example

{
  "job_id": "job_customer_sync",
  "operation": "customers.UpsertPerson",
  "file_id": "f_customers",
  "status": "queued",
  "processed": 500,
  "created": 400,
  "updated": 99,
  "failed": 1,
  "error_code": null
}

Illustrative values, not a live response.