List sender IDs

GET/v1/sender-ids

Lists your sender IDs, newest first, with their status and whether each can be used to send now.

Scope

sender_ids:read

Request

Every request needs an API key in the Authorization header, and the key needs the scope the endpoint names.

Parameters

• statusqueryarray of string

  Only sender IDs with this status. Repeat it for several.

  • One of: pending, approved, rejected, suspended, withdrawn
• limitqueryinteger

  How many items to return, from 1 to 100 (50 by default).

  • From 1 to 100
  • Defaults to 50
• cursorquerystring

  The next_cursor of the previous page.

  • At most 256 characters

GET /v1/sender-ids?status=approved

Responses

200 OK

ReturnsSenderIdList

• dataarray of SenderIdRequired

  Your sender IDs on this page, newest first.

• next_cursorstringor nullRequired

  Pass this back as cursor for the next page; null on the last page.

Headers

• Cache-ControlstringRequired

  Responses are never cached.

• RateLimit-Limitinteger

  Requests per second your account may sustain.

• RateLimit-Remaininginteger

  Whole requests left in your account's bucket.

• RateLimit-Resetinteger

  Seconds until the bucket is full again.

• X-Request-IdstringRequired

  This request's ID, also given as request_id in error bodies. Quote it to support.

{  "data": [    {      "id": "sid_01M3KR6CEGVQVV5PV6Q9J1G6SP",      "object": "sender_id",      "created_at": "2026-09-20T09:00:00.000Z",      "decided_at": "2026-09-21T11:30:00.000Z",      "ready": true,      "status": "approved",      "status_reason": null,      "updated_at": "2026-09-21T11:30:00.000Z",      "usable": true,      "value": "ACME"    }  ],  "next_cursor": null}

Errors

Each code links to its page. Branch on the code, never on the title or detail.

• 401 Unauthorized
  • unauthenticated
• 403 Forbidden
  • insufficient_scope
  • ip_not_allowed
• 413 Content Too Large
  • payload_too_large
• 415 Unsupported Media Type
  • unsupported_media_type
• 422 Unprocessable Content
  • validation_error
• 429 Too Many Requests
  • rate_limited
• 500 Internal Server Error
  • internal_error
• 503 Service Unavailable
  • service_unavailable

{  "type": "https://docs.messaging.500calls.com/errors/validation_error",  "title": "Validation error",  "status": 422,  "code": "validation_error",  "detail": "1 field failed validation.",  "request_id": "req_01M3KR6CQ26S90NG2V790GVFTX",  "errors": [    {      "field": "limit",      "code": "out_of_range",      "message": "Input should be greater than or equal to 1"    }  ]}

Code samples

Each sample reads your key from the API_KEY_500CALLS environment variable.

curl 'https://api.messaging.500calls.com/v1/sender-ids?status=approved' \  -H "Authorization: Bearer $API_KEY_500CALLS"

import osimport requestsresponse = requests.get(    "https://api.messaging.500calls.com/v1/sender-ids?status=approved",    headers={        "Authorization": f"Bearer {os.environ['API_KEY_500CALLS']}",    },    timeout=30,)print(response.status_code, response.json())

const response = await fetch("https://api.messaging.500calls.com/v1/sender-ids?status=approved", {  headers: {    Authorization: `Bearer ${process.env.API_KEY_500CALLS}`,  },});console.log(response.status, await response.json());

<?php$curl = curl_init('https://api.messaging.500calls.com/v1/sender-ids?status=approved');curl_setopt_array($curl, [    CURLOPT_HTTPHEADER => [        'Authorization: Bearer ' . getenv('API_KEY_500CALLS'),    ],    CURLOPT_RETURNTRANSFER => true,]);$body = curl_exec($curl);$status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);echo $status, PHP_EOL, $body, PHP_EOL;