First-request guide for Create person list export job.
Export API guide
Export person lists
Start an asynchronous export for the person-list scope your integration needs.
On this page: QuickstartRequest anatomyResponse anatomyRules and constraintsEmpty resultsErrors and recoveryNext steps
Before you start
Common workflows
Quickstart
Request anatomy
| Part | Required | What to send |
|---|---|---|
| jobName | required | Client-readable name for the asynchronous job. |
| personListIds | optional | Array of person-list identifiers for a selected export. |
Response anatomy
| Field | Type / state | How to use it |
|---|---|---|
| entityType | personlist | Identifies this as a person-list export. |
| jobId | string | Identifier used with the status endpoint. |
| jobStatus | accepted | The export has been queued. |
| createdAt | timestamp | Creation time in ISO-8601 format. |
Rules and constraints
- Use the supported person-list scope and keep list IDs as integers.
- Persist jobId before polling so retries can resume after a network failure.
- Do not treat HTTP 202 or accepted status as a completed download.
Empty results
An empty file can mean the selected lists have no accessible members. Recheck list IDs, tenant permissions, and membership timing.
Errors and recovery
Handle these responses explicitly so your integration can report an actionable cause and next step.
| Status | Meaning | Recovery |
|---|---|---|
| 400 | The person-list request is malformed. | Validate jobName and personListIds, including their types and supported scope. |
| 401 | The bearer token is missing, expired, or invalid. | Refresh the token and retry after authentication succeeds. |
| 403 | The caller cannot access the requested person lists. | Check tenant membership and list permissions. |
| 429 | The API rate limit was exceeded. | Back off and retry without duplicating an in-flight job. |