GET
/lists/{id}/contactsGET /lists/{id}/contacts
List the contacts in a list.
Request
curl -X GET 'https://api.sendheron.com/api/v1/lists/{id}/contacts' \
-H 'Authorization: Bearer <YOUR_API_KEY>' \
-H 'Content-Type: application/json'Required scopes
The key must carry these:
- contacts:read
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| id | uuid | Yes | List UUID. |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
| page | integer | No | Zero-based page number. Defaults to 0. The answer is the list envelope. |
| limit | integer | No | Items per page, from 1 to 100. Defaults to 50. |
| term | string | No | Partial match on the email, first name or last name. |
Responses
Returns 200 on success.
- 400
- The payload failed validation, or the request is not valid for the current state.
messagesays which kind of refusal it is, and for a payload that failed validation (validationFailed) thedescriptionnames the field and says what was wrong with it in words, e.g. "domain: domain must be a bare hostname such as acme.com, with no scheme, path, or port". An id in the path that is not a UUID answersinvalidUUIDon every route. - 401
- Missing or invalid API key.
- 403
- Valid key, but it does not carry the required scope.
messageisapiKeys.insufficientScopesand thedescriptionnames both halves of the problem: "Missing required scope(s): X. This key holds: Y." Neither is a secret, since the required scopes are on this page and the held ones are your own credential, and a bare "Forbidden" costs a debugging pass to work out which of the two it was. - 404
- No such record in this workspace. An id belonging to a different workspace returns this too, never a 403, because the API will not confirm that a record exists outside the workspace your key was issued in. Read it as "not yours or not there" rather than as "definitely gone".
- 409
- A duplicate, or an idempotency key reused with a different payload.
- 429
- Either rate-limit ceiling was exceeded.
messageistooManyRequests, and theRetry-Afterheader says how many seconds until the window rolls.
Rate limits
100/min per key, counted against the organization's READ ceiling (1200/min). Both windows are one minute.