Export a resource's list to a file.

The export runs as a job: poll the export for its link, or listen for export.completed. History (messages, attempts, delivery_events, inbound_messages) includes the periods already archived out of the database.

POST/v1/exports

Authorization

AuthorizationBearer token · headerrequired

An API key (nb_live_…, nb_test_…), a workspace token (nbs_…) or a CLI token (nbc_…).

Header parameters

Idempotency-Keystringrequired

A stable key for this logical request; reuse it when retrying.

min length 1 · max length 128 · matches ^[!-~]+$

Request body

requiredapplication/json

filtersobject | null

The filters of the resource's list. For people: email, group_id, segment_id, q, created_at[gte] and the other ranges. For history, created_at[gte] and created_at[lt] (when a message was created, an attempt claimed, an event recorded, an inbound message received) and: for messages, campaign_id, connection_id, person_id, thread_id, state; for attempts, message_id, connection_id; for delivery_events, message_id, kind; for inbound_messages, message_id, connection_id, person_id, thread_id, classification.

formatExportFormat | null

Show properties

One of:

ExportFormat

string

null

null

resourceExportResourcerequired

What an export contains.

Allowed:peoplemessagesattemptsdelivery_eventsinbound_messages

Responses

202

The export, queued; Location names it.

created_atTimestamprequired

expires_atTimestamprequired

When the file is deleted.

filtersobjectrequired

The filters of the resource's list the file applies.

formatExportFormatrequired

The file's format.

Allowed:csvjsonl

idId_Exportrequired

matches ^exp_[0-9a-f]{32}$

job_idId_Job | null

Show properties

One of:

Id_Job

string

null

null

last_errorLastError | null

Show properties

One of:

LastError

atTimestamprequired

When the job's row last changed: the moment of the error for a job that ended, and at or after it while the job is still waiting or running (the row keeps no separate time for its error).

codestringrequired

A short machine-readable code (error, lease_expired, unknown_kind, cancelled, …).

detailstringrequired

A human-readable explanation.

null

null

resourceExportResourcerequired

What an export contains.

Allowed:peoplemessagesattemptsdelivery_eventsinbound_messages

rowsinteger<int64> | null

The rows in the file, once it is ready.

statusExportStatusrequired

Where an export is, as the API shows it: queued and running while its job writes the file, ready with a link, failed, or expired once its file's days are over. The row stores the first four; expired is read from expires_at, and a job that ended without finishing reads as failed.

Allowed:queuedrunningreadyfailedexpired

updated_atTimestamprequired

urlstring | null

The file, when ready: a link that works for 15 minutes from this read.

401

No valid credential.

codeProblemCoderequired

The closed registry of problem codes: programs branch on a problem's code, never on its text. A code may be added, never repurposed.

Allowed:invalid_requestunauthorizedforbiddensession_requirednot_foundarchivedmethod_not_allowedconflictinvalid_stateidempotency_in_progressprecondition_failedpayload_too_largeunsupported_media_typevalidation_failedidempotency_mismatchsuppressedcaptcha_failedinsufficient_scoperate_limitedquota_exceededinternal_errorservice_unavailabletimeout

detailstringrequired

What went wrong, for a person; never an internal cause.

errorsFieldError[]

With validation_failed only: every invalid field.

Show properties

Array of FieldError

codestringrequired

What is wrong (required, range, length, format, invalid, …).

detailstringrequired

A safe, human-readable explanation.

pointerstringrequired

RFC 6901 pointer into the body, or ?name for a query parameter.

instancestringrequired

The request's path.

request_idstringrequired

The request's id, also in X-Request-Id: what support needs to find the request.

retry_afterinteger<int64> | null

With 429 and 503: the seconds to wait, as in Retry-After.

min 0

statusinteger<int32>required

The HTTP status.

min 0

titlestringrequired

Fixed per code.

typestringrequired

https://docs.norbelys.com/errors/<code>, a page that explains the code.

403

The credential lacks people:write (people), messages:read (messages, attempts, delivery events) or inbox:read (inbound messages).

codeProblemCoderequired

The closed registry of problem codes: programs branch on a problem's code, never on its text. A code may be added, never repurposed.

detailstringrequired

What went wrong, for a person; never an internal cause.

errorsFieldError[]

With validation_failed only: every invalid field.

Show properties

Array of FieldError

codestringrequired

What is wrong (required, range, length, format, invalid, …).

detailstringrequired

A safe, human-readable explanation.

pointerstringrequired

RFC 6901 pointer into the body, or ?name for a query parameter.

instancestringrequired

The request's path.

request_idstringrequired

The request's id, also in X-Request-Id: what support needs to find the request.

retry_afterinteger<int64> | null

With 429 and 503: the seconds to wait, as in Retry-After.

min 0

statusinteger<int32>required

The HTTP status.

min 0

titlestringrequired

Fixed per code.

typestringrequired

https://docs.norbelys.com/errors/<code>, a page that explains the code.

404

The filters name a group or segment that does not exist.

codeProblemCoderequired

The closed registry of problem codes: programs branch on a problem's code, never on its text. A code may be added, never repurposed.

detailstringrequired

What went wrong, for a person; never an internal cause.

errorsFieldError[]

With validation_failed only: every invalid field.

Show properties

Array of FieldError

codestringrequired

What is wrong (required, range, length, format, invalid, …).

detailstringrequired

A safe, human-readable explanation.

pointerstringrequired

RFC 6901 pointer into the body, or ?name for a query parameter.

instancestringrequired

The request's path.

request_idstringrequired

The request's id, also in X-Request-Id: what support needs to find the request.

retry_afterinteger<int64> | null

With 429 and 503: the seconds to wait, as in Retry-After.

min 0

statusinteger<int32>required

The HTTP status.

min 0

titlestringrequired

Fixed per code.

typestringrequired

https://docs.norbelys.com/errors/<code>, a page that explains the code.

422

The body is invalid.

codeProblemCoderequired

The closed registry of problem codes: programs branch on a problem's code, never on its text. A code may be added, never repurposed.

detailstringrequired

What went wrong, for a person; never an internal cause.

errorsFieldError[]

With validation_failed only: every invalid field.

Show properties

Array of FieldError

codestringrequired

What is wrong (required, range, length, format, invalid, …).

detailstringrequired

A safe, human-readable explanation.

pointerstringrequired

RFC 6901 pointer into the body, or ?name for a query parameter.

instancestringrequired

The request's path.

request_idstringrequired

The request's id, also in X-Request-Id: what support needs to find the request.

retry_afterinteger<int64> | null

With 429 and 503: the seconds to wait, as in Retry-After.

min 0

statusinteger<int32>required

The HTTP status.

min 0

titlestringrequired

Fixed per code.

typestringrequired

https://docs.norbelys.com/errors/<code>, a page that explains the code.

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

Bearer tokenRemember on this deviceInclude my values in samples

Parameters

Idempotency-Keyheader*A stable key for this logical request; reuse it when retrying.

Bodyapplication/json

Request body

Request

curl -X POST 'https://api.norbelys.com/v1/exports' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Idempotency-Key: string' \
  -H 'Content-Type: application/json' \
  -d '{
  "filters": {
    "group_id": "grp_0190f8a2b4c87a10b6d2e4f6a8c0e2f4"
  },
  "format": "csv",
  "resource": "people"
}'

const response = await fetch("https://api.norbelys.com/v1/exports", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Idempotency-Key": "string",
    "Content-Type": "application/json"
  },
  body: "{\n  \"filters\": {\n    \"group_id\": \"grp_0190f8a2b4c87a10b6d2e4f6a8c0e2f4\"\n  },\n  \"format\": \"csv\",\n  \"resource\": \"people\"\n}"
});

import requests

response = requests.post(
    "https://api.norbelys.com/v1/exports",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Idempotency-Key": "string",
        "Content-Type": "application/json"
    },
    data="{\n  \"filters\": {\n    \"group_id\": \"grp_0190f8a2b4c87a10b6d2e4f6a8c0e2f4\"\n  },\n  \"format\": \"csv\",\n  \"resource\": \"people\"\n}",
)

Response

{
  "created_at": "2019-08-24T14:15:22Z",
  "expires_at": "2019-08-24T14:15:22Z",
  "filters": {},
  "format": "csv",
  "id": "exp_0190f8a2b4c87a10b6d2e4f6a8c0e2f4",
  "job_id": "job_0190f8a2b4c87a10b6d2e4f6a8c0e2f4",
  "last_error": {
    "at": "2019-08-24T14:15:22Z",
    "code": "string",
    "detail": "string"
  },
  "resource": "people",
  "rows": 0,
  "status": "queued",
  "updated_at": "2019-08-24T14:15:22Z",
  "url": "string"
}

{
  "code": "invalid_request",
  "detail": "string",
  "errors": [
    {
      "code": "string",
      "detail": "string",
      "pointer": "string"
    }
  ],
  "instance": "string",
  "request_id": "string",
  "retry_after": 0,
  "status": 0,
  "title": "string",
  "type": "string"
}

{
  "code": "invalid_request",
  "detail": "string",
  "errors": [
    {
      "code": "string",
      "detail": "string",
      "pointer": "string"
    }
  ],
  "instance": "string",
  "request_id": "string",
  "retry_after": 0,
  "status": 0,
  "title": "string",
  "type": "string"
}

{
  "code": "invalid_request",
  "detail": "string",
  "errors": [
    {
      "code": "string",
      "detail": "string",
      "pointer": "string"
    }
  ],
  "instance": "string",
  "request_id": "string",
  "retry_after": 0,
  "status": 0,
  "title": "string",
  "type": "string"
}

{
  "code": "invalid_request",
  "detail": "string",
  "errors": [
    {
      "code": "string",
      "detail": "string",
      "pointer": "string"
    }
  ],
  "instance": "string",
  "request_id": "string",
  "retry_after": 0,
  "status": 0,
  "title": "string",
  "type": "string"
}