{"openapi":"3.1.0","info":{"title":"500Calls public API","version":"v1","description":"Send SMS, follow their status, and read your balance and sender IDs. Clients must ignore response fields and enum values they do not recognise: adding either is not a breaking change within v1, while removing or retyping a field, making an optional field required or adding a message status needs a new version. A deprecated endpoint stays available for at least six months after it is announced, and its responses carry the Deprecation, Sunset and Link headers."},"servers":[{"url":"https://api.messaging.500calls.com"}],"tags":[{"name":"Sending","description":"Send one SMS, the same SMS to many recipients, or a personalised batch."},{"name":"Messages","description":"Read, list and cancel the messages you have sent."},{"name":"Balance","description":"Read your wallet balance."},{"name":"Sender IDs","description":"List your sender IDs and whether each can be used now."}],"paths":{"/v1/balance":{"get":{"summary":"Get the wallet balance","operationId":"getBalance","responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BalanceEnvelope"},"example":{"data":{"object":"balance","currency":"NGN","balance":"15250.0000","held":"35.0000","available":"15215.0000","low_balance_threshold":"1000.0000","as_of":"2026-09-28T10:15:30.000Z"}}}}},"401":{"description":"unauthenticated","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"value":{"type":"https://docs.messaging.500calls.com/errors/unauthenticated","title":"Authentication required","status":401,"code":"unauthenticated","detail":"Send a valid API key in the header 'Authorization: Bearer <key>'.","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"403":{"description":"ip_not_allowed, insufficient_scope","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ip_not_allowed":{"value":{"type":"https://docs.messaging.500calls.com/errors/ip_not_allowed","title":"IP address not allowed","status":403,"code":"ip_not_allowed","detail":"IP address not allowed","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}},"insufficient_scope":{"value":{"type":"https://docs.messaging.500calls.com/errors/insufficient_scope","title":"Insufficient scope","status":403,"code":"insufficient_scope","detail":"This API key does not have the balance:read scope.","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"413":{"description":"payload_too_large","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"payload_too_large":{"value":{"type":"https://docs.messaging.500calls.com/errors/payload_too_large","title":"Payload too large","status":413,"code":"payload_too_large","detail":"Payload too large","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"415":{"description":"unsupported_media_type","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unsupported_media_type":{"value":{"type":"https://docs.messaging.500calls.com/errors/unsupported_media_type","title":"Unsupported media type","status":415,"code":"unsupported_media_type","detail":"Unsupported media type","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"429":{"description":"rate_limited","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"value":{"type":"https://docs.messaging.500calls.com/errors/rate_limited","title":"Too many requests","status":429,"code":"rate_limited","detail":"quota_exceeded:public_api_rate","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"500":{"description":"internal_error","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal_error":{"value":{"type":"https://docs.messaging.500calls.com/errors/internal_error","title":"Internal error","status":500,"code":"internal_error","detail":"Internal error","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"503":{"description":"service_unavailable","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"service_unavailable":{"value":{"type":"https://docs.messaging.500calls.com/errors/service_unavailable","title":"Service unavailable","status":503,"code":"service_unavailable","detail":"Service unavailable","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}}},"tags":["Balance"],"security":[{"bearerAuth":["balance:read"]}],"description":"Returns the wallet balance, the funds held for messages in flight and what new sends may use.","x-request-example":"GET /v1/balance"}},"/v1/messages":{"post":{"summary":"Send one SMS (deprecated)","description":"Deprecated: use `POST /v1/sms/messages`, which takes the same body and gives the same responses. Every response carries the Deprecation and Sunset headers, which give the removal date, and a Link header to the migration guide.","operationId":"sendMessageDeprecated","deprecated":true,"responses":{"202":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"},"Location":{"$ref":"#/components/headers/Location"},"Deprecation":{"description":"This endpoint is deprecated. A request refused before it reaches the endpoint (413, 415) has none.","schema":{"type":"string","const":"true"},"required":true},"Sunset":{"description":"The HTTP-date after which this endpoint may be removed. A request refused before it reaches the endpoint (413, 415) has none.","schema":{"type":"string"},"required":true,"example":"Thu, 15 Apr 2027 00:00:00 GMT"},"Link":{"description":"The migration guide, as `<url>; rel=\"deprecation\"`. A request refused before it reaches the endpoint (413, 415) has none.","schema":{"type":"string"},"required":true,"example":"<https://docs.messaging.500calls.com/api/migrations/send-endpoint>; rel=\"deprecation\""}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageEnvelope"},"example":{"data":{"id":"msg_01M3KR6CEGVQVV5PV6Q9J1G6SP","object":"message","mode":"live","channel":"sms","direction":"outbound","status":"queued","to":"+2348031234567","from":"ACME","body":"Your ACME code is 482913. It expires in 5 minutes.","encoding":"gsm7","segments":1,"held_amount":"3.5000","unit_price":null,"amount":null,"currency":"NGN","client_reference":"order-78123","campaign_id":null,"source":"api","error":null,"scheduled_at":null,"created_at":"2026-09-28T10:15:30.000Z","sent_at":null,"completed_at":null,"updated_at":"2026-09-28T10:15:30.000Z"}}}}},"401":{"description":"unauthenticated","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"Deprecation":{"description":"This endpoint is deprecated. A request refused before it reaches the endpoint (413, 415) has none.","schema":{"type":"string","const":"true"},"required":true},"Sunset":{"description":"The HTTP-date after which this endpoint may be removed. A request refused before it reaches the endpoint (413, 415) has none.","schema":{"type":"string"},"required":true,"example":"Thu, 15 Apr 2027 00:00:00 GMT"},"Link":{"description":"The migration guide, as `<url>; rel=\"deprecation\"`. A request refused before it reaches the endpoint (413, 415) has none.","schema":{"type":"string"},"required":true,"example":"<https://docs.messaging.500calls.com/api/migrations/send-endpoint>; rel=\"deprecation\""}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"value":{"type":"https://docs.messaging.500calls.com/errors/unauthenticated","title":"Authentication required","status":401,"code":"unauthenticated","detail":"Send a valid API key in the header 'Authorization: Bearer <key>'.","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"402":{"description":"insufficient_balance","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Deprecation":{"description":"This endpoint is deprecated. A request refused before it reaches the endpoint (413, 415) has none.","schema":{"type":"string","const":"true"},"required":true},"Sunset":{"description":"The HTTP-date after which this endpoint may be removed. A request refused before it reaches the endpoint (413, 415) has none.","schema":{"type":"string"},"required":true,"example":"Thu, 15 Apr 2027 00:00:00 GMT"},"Link":{"description":"The migration guide, as `<url>; rel=\"deprecation\"`. A request refused before it reaches the endpoint (413, 415) has none.","schema":{"type":"string"},"required":true,"example":"<https://docs.messaging.500calls.com/api/migrations/send-endpoint>; rel=\"deprecation\""}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"insufficient_balance":{"value":{"type":"https://docs.messaging.500calls.com/errors/insufficient_balance","title":"Insufficient balance","status":402,"code":"insufficient_balance","detail":"This request needs a hold of NGN 3.5000 but your available balance is NGN 1.2000. No messages were accepted.","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[],"required_amount":"3.5000","available_amount":"1.2000","currency":"NGN"}}}}}},"403":{"description":"ip_not_allowed, insufficient_scope, email_not_verified, tenant_suspended","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"Deprecation":{"description":"This endpoint is deprecated. A request refused before it reaches the endpoint (413, 415) has none.","schema":{"type":"string","const":"true"},"required":true},"Sunset":{"description":"The HTTP-date after which this endpoint may be removed. A request refused before it reaches the endpoint (413, 415) has none.","schema":{"type":"string"},"required":true,"example":"Thu, 15 Apr 2027 00:00:00 GMT"},"Link":{"description":"The migration guide, as `<url>; rel=\"deprecation\"`. A request refused before it reaches the endpoint (413, 415) has none.","schema":{"type":"string"},"required":true,"example":"<https://docs.messaging.500calls.com/api/migrations/send-endpoint>; rel=\"deprecation\""}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ip_not_allowed":{"value":{"type":"https://docs.messaging.500calls.com/errors/ip_not_allowed","title":"IP address not allowed","status":403,"code":"ip_not_allowed","detail":"IP address not allowed","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}},"insufficient_scope":{"value":{"type":"https://docs.messaging.500calls.com/errors/insufficient_scope","title":"Insufficient scope","status":403,"code":"insufficient_scope","detail":"This API key does not have the messages:send scope.","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}},"email_not_verified":{"value":{"type":"https://docs.messaging.500calls.com/errors/email_not_verified","title":"Email address not verified","status":403,"code":"email_not_verified","detail":"Email address not verified","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}},"tenant_suspended":{"value":{"type":"https://docs.messaging.500calls.com/errors/tenant_suspended","title":"Account suspended","status":403,"code":"tenant_suspended","detail":"Your account is suspended; sending is paused.","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"409":{"description":"conflict, idempotency_key_reused","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Deprecation":{"description":"This endpoint is deprecated. A request refused before it reaches the endpoint (413, 415) has none.","schema":{"type":"string","const":"true"},"required":true},"Sunset":{"description":"The HTTP-date after which this endpoint may be removed. A request refused before it reaches the endpoint (413, 415) has none.","schema":{"type":"string"},"required":true,"example":"Thu, 15 Apr 2027 00:00:00 GMT"},"Link":{"description":"The migration guide, as `<url>; rel=\"deprecation\"`. A request refused before it reaches the endpoint (413, 415) has none.","schema":{"type":"string"},"required":true,"example":"<https://docs.messaging.500calls.com/api/migrations/send-endpoint>; rel=\"deprecation\""}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"conflict":{"value":{"type":"https://docs.messaging.500calls.com/errors/conflict","title":"Conflict","status":409,"code":"conflict","detail":"A request with this Idempotency-Key is in progress.","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}},"idempotency_key_reused":{"value":{"type":"https://docs.messaging.500calls.com/errors/idempotency_key_reused","title":"Idempotency key reused","status":409,"code":"idempotency_key_reused","detail":"This Idempotency-Key was already used with a different request body.","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"413":{"description":"payload_too_large","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"Deprecation":{"description":"This endpoint is deprecated. A request refused before it reaches the endpoint (413, 415) has none.","schema":{"type":"string","const":"true"}},"Sunset":{"description":"The HTTP-date after which this endpoint may be removed. A request refused before it reaches the endpoint (413, 415) has none.","schema":{"type":"string"},"example":"Thu, 15 Apr 2027 00:00:00 GMT"},"Link":{"description":"The migration guide, as `<url>; rel=\"deprecation\"`. A request refused before it reaches the endpoint (413, 415) has none.","schema":{"type":"string"},"example":"<https://docs.messaging.500calls.com/api/migrations/send-endpoint>; rel=\"deprecation\""}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"payload_too_large":{"value":{"type":"https://docs.messaging.500calls.com/errors/payload_too_large","title":"Payload too large","status":413,"code":"payload_too_large","detail":"Payload too large","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"415":{"description":"unsupported_media_type","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"Deprecation":{"description":"This endpoint is deprecated. A request refused before it reaches the endpoint (413, 415) has none.","schema":{"type":"string","const":"true"}},"Sunset":{"description":"The HTTP-date after which this endpoint may be removed. A request refused before it reaches the endpoint (413, 415) has none.","schema":{"type":"string"},"example":"Thu, 15 Apr 2027 00:00:00 GMT"},"Link":{"description":"The migration guide, as `<url>; rel=\"deprecation\"`. A request refused before it reaches the endpoint (413, 415) has none.","schema":{"type":"string"},"example":"<https://docs.messaging.500calls.com/api/migrations/send-endpoint>; rel=\"deprecation\""}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unsupported_media_type":{"value":{"type":"https://docs.messaging.500calls.com/errors/unsupported_media_type","title":"Unsupported media type","status":415,"code":"unsupported_media_type","detail":"Unsupported media type","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"422":{"description":"validation_error, sender_id_not_approved","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Deprecation":{"description":"This endpoint is deprecated. A request refused before it reaches the endpoint (413, 415) has none.","schema":{"type":"string","const":"true"},"required":true},"Sunset":{"description":"The HTTP-date after which this endpoint may be removed. A request refused before it reaches the endpoint (413, 415) has none.","schema":{"type":"string"},"required":true,"example":"Thu, 15 Apr 2027 00:00:00 GMT"},"Link":{"description":"The migration guide, as `<url>; rel=\"deprecation\"`. A request refused before it reaches the endpoint (413, 415) has none.","schema":{"type":"string"},"required":true,"example":"<https://docs.messaging.500calls.com/api/migrations/send-endpoint>; rel=\"deprecation\""}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_error":{"value":{"type":"https://docs.messaging.500calls.com/errors/validation_error","title":"Validation error","status":422,"code":"validation_error","detail":"No recipient could be accepted. No message was created.","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[{"field":"to","code":"invalid_recipient","message":"Not a valid mobile number."}]}},"sender_id_not_approved":{"value":{"type":"https://docs.messaging.500calls.com/errors/sender_id_not_approved","title":"Sender ID not approved","status":422,"code":"sender_id_not_approved","detail":"Sender ID not approved","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"429":{"description":"rate_limited","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"Deprecation":{"description":"This endpoint is deprecated. A request refused before it reaches the endpoint (413, 415) has none.","schema":{"type":"string","const":"true"},"required":true},"Sunset":{"description":"The HTTP-date after which this endpoint may be removed. A request refused before it reaches the endpoint (413, 415) has none.","schema":{"type":"string"},"required":true,"example":"Thu, 15 Apr 2027 00:00:00 GMT"},"Link":{"description":"The migration guide, as `<url>; rel=\"deprecation\"`. A request refused before it reaches the endpoint (413, 415) has none.","schema":{"type":"string"},"required":true,"example":"<https://docs.messaging.500calls.com/api/migrations/send-endpoint>; rel=\"deprecation\""}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"value":{"type":"https://docs.messaging.500calls.com/errors/rate_limited","title":"Too many requests","status":429,"code":"rate_limited","detail":"quota_exceeded:public_api_rate","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"500":{"description":"internal_error","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Deprecation":{"description":"This endpoint is deprecated. A request refused before it reaches the endpoint (413, 415) has none.","schema":{"type":"string","const":"true"},"required":true},"Sunset":{"description":"The HTTP-date after which this endpoint may be removed. A request refused before it reaches the endpoint (413, 415) has none.","schema":{"type":"string"},"required":true,"example":"Thu, 15 Apr 2027 00:00:00 GMT"},"Link":{"description":"The migration guide, as `<url>; rel=\"deprecation\"`. A request refused before it reaches the endpoint (413, 415) has none.","schema":{"type":"string"},"required":true,"example":"<https://docs.messaging.500calls.com/api/migrations/send-endpoint>; rel=\"deprecation\""}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal_error":{"value":{"type":"https://docs.messaging.500calls.com/errors/internal_error","title":"Internal error","status":500,"code":"internal_error","detail":"Internal error","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"503":{"description":"service_unavailable","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"Deprecation":{"description":"This endpoint is deprecated. A request refused before it reaches the endpoint (413, 415) has none.","schema":{"type":"string","const":"true"},"required":true},"Sunset":{"description":"The HTTP-date after which this endpoint may be removed. A request refused before it reaches the endpoint (413, 415) has none.","schema":{"type":"string"},"required":true,"example":"Thu, 15 Apr 2027 00:00:00 GMT"},"Link":{"description":"The migration guide, as `<url>; rel=\"deprecation\"`. A request refused before it reaches the endpoint (413, 415) has none.","schema":{"type":"string"},"required":true,"example":"<https://docs.messaging.500calls.com/api/migrations/send-endpoint>; rel=\"deprecation\""}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"service_unavailable":{"value":{"type":"https://docs.messaging.500calls.com/errors/service_unavailable","title":"Service unavailable","status":503,"code":"service_unavailable","detail":"Service unavailable","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SingleSendIn"},"example":{"to":"08031234567","from":"ACME","body":"Your ACME code is 482913. It expires in 5 minutes.","client_reference":"order-78123"}}}},"tags":["Sending"],"security":[{"bearerAuth":["messages:send"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"1 to 64 characters from A-Z, a-z, 0-9, `_` and `-`. Repeating a request with the same key and body within 24 hours returns the stored success response without acting again; the same key with a different body is refused with 409.","schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,64}$"},"example":"order-78123-otp"}],"x-sunset":"2027-04-15"},"get":{"summary":"List messages","operationId":"listMessages","parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","enum":["scheduled","queued","sent","delivered","undelivered","expired","rejected","failed","cancelled"]}},"description":"Only messages with this status. Repeat it for several; `queued` also matches messages being sent."},{"name":"from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"From"},"description":"Only messages from this sender ID (not case-sensitive)."},{"name":"to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"To"},"description":"Only messages to this recipient, in any format a send accepts."},{"name":"client_reference","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Client Reference"},"description":"Only messages with exactly this reference."},{"name":"campaign_id","in":"query","required":false,"schema":{"type":"string","pattern":"^cmp_[0-9A-HJKMNP-TV-Z]{26}$"},"description":"Only messages of this campaign, `cmp_…`."},{"name":"source","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","enum":["api","campaign","quick_send","test_send"]}},"description":"Only messages sent this way. Repeat it for several."},{"name":"created_after","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created After"},"description":"Only messages created at or after this time, at most 12 months ago. With neither bound, the last 7 days are listed."},{"name":"created_before","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created Before"},"description":"Only messages created before this time (now by default). With only `created_before`, the 7 days before it are listed. One request spans at most 92 days by default."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":50,"title":"Limit"},"description":"How many items to return, from 1 to 100 (50 by default)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Cursor"},"description":"The `next_cursor` of the previous page."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageList"},"example":{"data":[{"id":"msg_01M3KR6CEGVQVV5PV6Q9J1G6SP","object":"message","mode":"live","channel":"sms","direction":"outbound","status":"delivered","to":"+2348031234567","from":"ACME","body":"Your ACME code is 482913. It expires in 5 minutes.","encoding":"gsm7","segments":1,"held_amount":"3.5000","unit_price":"3.2000","amount":"3.2000","currency":"NGN","client_reference":"order-78123","campaign_id":null,"source":"api","error":null,"scheduled_at":null,"created_at":"2026-09-28T10:15:30.000Z","sent_at":"2026-09-28T10:15:31.412Z","completed_at":"2026-09-28T10:15:39.870Z","updated_at":"2026-09-28T10:15:39.870Z"}],"next_cursor":null}}}},"401":{"description":"unauthenticated","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"value":{"type":"https://docs.messaging.500calls.com/errors/unauthenticated","title":"Authentication required","status":401,"code":"unauthenticated","detail":"Send a valid API key in the header 'Authorization: Bearer <key>'.","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"403":{"description":"ip_not_allowed, insufficient_scope","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ip_not_allowed":{"value":{"type":"https://docs.messaging.500calls.com/errors/ip_not_allowed","title":"IP address not allowed","status":403,"code":"ip_not_allowed","detail":"IP address not allowed","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}},"insufficient_scope":{"value":{"type":"https://docs.messaging.500calls.com/errors/insufficient_scope","title":"Insufficient scope","status":403,"code":"insufficient_scope","detail":"This API key does not have the messages:read scope.","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"413":{"description":"payload_too_large","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"payload_too_large":{"value":{"type":"https://docs.messaging.500calls.com/errors/payload_too_large","title":"Payload too large","status":413,"code":"payload_too_large","detail":"Payload too large","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"415":{"description":"unsupported_media_type","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unsupported_media_type":{"value":{"type":"https://docs.messaging.500calls.com/errors/unsupported_media_type","title":"Unsupported media type","status":415,"code":"unsupported_media_type","detail":"Unsupported media type","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"422":{"description":"validation_error","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_error":{"value":{"type":"https://docs.messaging.500calls.com/errors/validation_error","title":"Validation error","status":422,"code":"validation_error","detail":"1 parameter failed validation.","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[{"field":"created_before","code":"range_too_large","message":"created_before can be at most 92 days after created_after (created_before defaults to now)."}]}}}}}},"429":{"description":"rate_limited","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"value":{"type":"https://docs.messaging.500calls.com/errors/rate_limited","title":"Too many requests","status":429,"code":"rate_limited","detail":"quota_exceeded:public_api_rate","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"500":{"description":"internal_error","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal_error":{"value":{"type":"https://docs.messaging.500calls.com/errors/internal_error","title":"Internal error","status":500,"code":"internal_error","detail":"Internal error","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"503":{"description":"service_unavailable","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"service_unavailable":{"value":{"type":"https://docs.messaging.500calls.com/errors/service_unavailable","title":"Service unavailable","status":503,"code":"service_unavailable","detail":"Service unavailable","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}}},"tags":["Messages"],"security":[{"bearerAuth":["messages:read"]}],"description":"Lists messages newest first. Filters combine; `status` and `source` repeat. With neither time bound the last 7 days are listed, and one request spans at most the report range (92 days by default). Pass `next_cursor` back as `cursor` for the next page.","x-request-example":"GET /v1/messages?client_reference=order-78123&limit=10"}},"/v1/messages/{message_id}":{"get":{"summary":"Get a message","operationId":"getMessage","parameters":[{"name":"message_id","in":"path","required":true,"schema":{"type":"string","pattern":"^msg_[0-9A-HJKMNP-TV-Z]{26}$"},"description":"The message ID, `msg_…`."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageWithHistoryEnvelope"},"example":{"data":{"id":"msg_01M3KR6CEGVQVV5PV6Q9J1G6SP","object":"message","mode":"live","channel":"sms","direction":"outbound","status":"delivered","to":"+2348031234567","from":"ACME","body":"Your ACME code is 482913. It expires in 5 minutes.","encoding":"gsm7","segments":1,"held_amount":"3.5000","unit_price":"3.2000","amount":"3.2000","currency":"NGN","client_reference":"order-78123","campaign_id":null,"source":"api","error":null,"scheduled_at":null,"created_at":"2026-09-28T10:15:30.000Z","sent_at":"2026-09-28T10:15:31.412Z","completed_at":"2026-09-28T10:15:39.870Z","updated_at":"2026-09-28T10:15:39.870Z","status_history":[{"status":"queued","occurred_at":"2026-09-28T10:15:30.000Z","error":null},{"status":"sent","occurred_at":"2026-09-28T10:15:31.412Z","error":null},{"status":"delivered","occurred_at":"2026-09-28T10:15:39.870Z","error":null}]}}}}},"401":{"description":"unauthenticated","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"value":{"type":"https://docs.messaging.500calls.com/errors/unauthenticated","title":"Authentication required","status":401,"code":"unauthenticated","detail":"Send a valid API key in the header 'Authorization: Bearer <key>'.","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"403":{"description":"ip_not_allowed, insufficient_scope","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ip_not_allowed":{"value":{"type":"https://docs.messaging.500calls.com/errors/ip_not_allowed","title":"IP address not allowed","status":403,"code":"ip_not_allowed","detail":"IP address not allowed","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}},"insufficient_scope":{"value":{"type":"https://docs.messaging.500calls.com/errors/insufficient_scope","title":"Insufficient scope","status":403,"code":"insufficient_scope","detail":"This API key does not have the messages:read scope.","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"404":{"description":"not_found","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"value":{"type":"https://docs.messaging.500calls.com/errors/not_found","title":"Not found","status":404,"code":"not_found","detail":"Not found","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"413":{"description":"payload_too_large","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"payload_too_large":{"value":{"type":"https://docs.messaging.500calls.com/errors/payload_too_large","title":"Payload too large","status":413,"code":"payload_too_large","detail":"Payload too large","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"415":{"description":"unsupported_media_type","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unsupported_media_type":{"value":{"type":"https://docs.messaging.500calls.com/errors/unsupported_media_type","title":"Unsupported media type","status":415,"code":"unsupported_media_type","detail":"Unsupported media type","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"429":{"description":"rate_limited","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"value":{"type":"https://docs.messaging.500calls.com/errors/rate_limited","title":"Too many requests","status":429,"code":"rate_limited","detail":"quota_exceeded:public_api_rate","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"500":{"description":"internal_error","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal_error":{"value":{"type":"https://docs.messaging.500calls.com/errors/internal_error","title":"Internal error","status":500,"code":"internal_error","detail":"Internal error","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"503":{"description":"service_unavailable","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"service_unavailable":{"value":{"type":"https://docs.messaging.500calls.com/errors/service_unavailable","title":"Service unavailable","status":503,"code":"service_unavailable","detail":"Service unavailable","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}}},"tags":["Messages"],"security":[{"bearerAuth":["messages:read"]}],"description":"Returns one message with its status history. An unknown ID, a malformed ID and another account's ID all return 404.","x-request-example":"GET /v1/messages/msg_01M3KR6CEGVQVV5PV6Q9J1G6SP"}},"/v1/messages/{message_id}/cancel":{"post":{"summary":"Cancel a message","description":"Cancels a message that is still scheduled or queued and releases its held funds, which return to your available balance at the next settlement step, within about a minute. Only messages sent through the API are cancelled here; a campaign's messages are cancelled with the campaign. A message that is already cancelled is returned unchanged. Send no body, or an empty JSON object `{}`: any member is refused with 422.","operationId":"cancelMessage","parameters":[{"name":"message_id","in":"path","required":true,"schema":{"type":"string","pattern":"^msg_[0-9A-HJKMNP-TV-Z]{26}$"},"description":"The ID of the message to cancel."},{"name":"Idempotency-Key","in":"header","required":false,"description":"1 to 64 characters from A-Z, a-z, 0-9, `_` and `-`. Repeating a request with the same key and body within 24 hours returns the stored success response without acting again; the same key with a different body is refused with 409.","schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,64}$"},"example":"order-78123-otp"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageEnvelope"},"example":{"data":{"id":"msg_01M3KR6CEGVQVV5PV6Q9J1G6SP","object":"message","mode":"live","channel":"sms","direction":"outbound","status":"cancelled","to":"+2348031234567","from":"ACME","body":"Your ACME code is 482913. It expires in 5 minutes.","encoding":"gsm7","segments":1,"held_amount":"3.5000","unit_price":null,"amount":"0.0000","currency":"NGN","client_reference":"order-78123","campaign_id":null,"source":"api","error":{"code":"cancelled_by_user","message":"Cancelled by the user."},"scheduled_at":null,"created_at":"2026-09-28T10:15:30.000Z","sent_at":null,"completed_at":"2026-09-28T10:16:02.000Z","updated_at":"2026-09-28T10:16:02.000Z"}}}}},"401":{"description":"unauthenticated","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"value":{"type":"https://docs.messaging.500calls.com/errors/unauthenticated","title":"Authentication required","status":401,"code":"unauthenticated","detail":"Send a valid API key in the header 'Authorization: Bearer <key>'.","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"403":{"description":"ip_not_allowed, insufficient_scope, email_not_verified, tenant_suspended","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ip_not_allowed":{"value":{"type":"https://docs.messaging.500calls.com/errors/ip_not_allowed","title":"IP address not allowed","status":403,"code":"ip_not_allowed","detail":"IP address not allowed","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}},"insufficient_scope":{"value":{"type":"https://docs.messaging.500calls.com/errors/insufficient_scope","title":"Insufficient scope","status":403,"code":"insufficient_scope","detail":"This API key does not have the messages:send scope.","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}},"email_not_verified":{"value":{"type":"https://docs.messaging.500calls.com/errors/email_not_verified","title":"Email address not verified","status":403,"code":"email_not_verified","detail":"Email address not verified","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}},"tenant_suspended":{"value":{"type":"https://docs.messaging.500calls.com/errors/tenant_suspended","title":"Account suspended","status":403,"code":"tenant_suspended","detail":"Your account is suspended; sending is paused.","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"404":{"description":"not_found","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"value":{"type":"https://docs.messaging.500calls.com/errors/not_found","title":"Not found","status":404,"code":"not_found","detail":"Not found","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"409":{"description":"conflict, invalid_state_transition","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"conflict":{"value":{"type":"https://docs.messaging.500calls.com/errors/conflict","title":"Conflict","status":409,"code":"conflict","detail":"A request with this Idempotency-Key is in progress.","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}},"invalid_state_transition":{"value":{"type":"https://docs.messaging.500calls.com/errors/invalid_state_transition","title":"Invalid state transition","status":409,"code":"invalid_state_transition","detail":"The message is sent and can no longer be cancelled.","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"413":{"description":"payload_too_large","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"payload_too_large":{"value":{"type":"https://docs.messaging.500calls.com/errors/payload_too_large","title":"Payload too large","status":413,"code":"payload_too_large","detail":"Payload too large","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"415":{"description":"unsupported_media_type","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unsupported_media_type":{"value":{"type":"https://docs.messaging.500calls.com/errors/unsupported_media_type","title":"Unsupported media type","status":415,"code":"unsupported_media_type","detail":"Unsupported media type","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"422":{"description":"validation_error","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_error":{"value":{"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":"reason","code":"unknown_field","message":"Extra inputs are not permitted"}]}}}}}},"429":{"description":"rate_limited","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"value":{"type":"https://docs.messaging.500calls.com/errors/rate_limited","title":"Too many requests","status":429,"code":"rate_limited","detail":"quota_exceeded:public_api_rate","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"500":{"description":"internal_error","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal_error":{"value":{"type":"https://docs.messaging.500calls.com/errors/internal_error","title":"Internal error","status":500,"code":"internal_error","detail":"Internal error","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"503":{"description":"service_unavailable","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"service_unavailable":{"value":{"type":"https://docs.messaging.500calls.com/errors/service_unavailable","title":"Service unavailable","status":503,"code":"service_unavailable","detail":"Service unavailable","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}}},"tags":["Messages"],"security":[{"bearerAuth":["messages:send"]}],"x-request-example":"POST /v1/messages/msg_01M3KR6CEGVQVV5PV6Q9J1G6SP/cancel"}},"/v1/sender-ids":{"get":{"summary":"List sender IDs","operationId":"listSenderIds","parameters":[{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"enum":["pending","approved","rejected","suspended","withdrawn"],"type":"string"}},{"type":"null"}],"title":"Status"},"description":"Only sender IDs with this status. Repeat it for several."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":50,"title":"Limit"},"description":"How many items to return, from 1 to 100 (50 by default)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Cursor"},"description":"The `next_cursor` of the previous page."}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SenderIdList"},"example":{"data":[{"object":"sender_id","id":"sid_01M3KR6CEGVQVV5PV6Q9J1G6SP","value":"ACME","status":"approved","ready":true,"usable":true,"status_reason":null,"created_at":"2026-09-20T09:00:00.000Z","decided_at":"2026-09-21T11:30:00.000Z","updated_at":"2026-09-21T11:30:00.000Z"}],"next_cursor":null}}}},"401":{"description":"unauthenticated","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"value":{"type":"https://docs.messaging.500calls.com/errors/unauthenticated","title":"Authentication required","status":401,"code":"unauthenticated","detail":"Send a valid API key in the header 'Authorization: Bearer <key>'.","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"403":{"description":"ip_not_allowed, insufficient_scope","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ip_not_allowed":{"value":{"type":"https://docs.messaging.500calls.com/errors/ip_not_allowed","title":"IP address not allowed","status":403,"code":"ip_not_allowed","detail":"IP address not allowed","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}},"insufficient_scope":{"value":{"type":"https://docs.messaging.500calls.com/errors/insufficient_scope","title":"Insufficient scope","status":403,"code":"insufficient_scope","detail":"This API key does not have the sender_ids:read scope.","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"413":{"description":"payload_too_large","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"payload_too_large":{"value":{"type":"https://docs.messaging.500calls.com/errors/payload_too_large","title":"Payload too large","status":413,"code":"payload_too_large","detail":"Payload too large","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"415":{"description":"unsupported_media_type","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unsupported_media_type":{"value":{"type":"https://docs.messaging.500calls.com/errors/unsupported_media_type","title":"Unsupported media type","status":415,"code":"unsupported_media_type","detail":"Unsupported media type","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"422":{"description":"validation_error","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_error":{"value":{"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"}]}}}}}},"429":{"description":"rate_limited","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"value":{"type":"https://docs.messaging.500calls.com/errors/rate_limited","title":"Too many requests","status":429,"code":"rate_limited","detail":"quota_exceeded:public_api_rate","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"500":{"description":"internal_error","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal_error":{"value":{"type":"https://docs.messaging.500calls.com/errors/internal_error","title":"Internal error","status":500,"code":"internal_error","detail":"Internal error","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"503":{"description":"service_unavailable","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"service_unavailable":{"value":{"type":"https://docs.messaging.500calls.com/errors/service_unavailable","title":"Service unavailable","status":503,"code":"service_unavailable","detail":"Service unavailable","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}}},"tags":["Sender IDs"],"security":[{"bearerAuth":["sender_ids:read"]}],"description":"Lists your sender IDs, newest first, with their status and whether each can be used to send now.","x-request-example":"GET /v1/sender-ids?status=approved"}},"/v1/sms/messages":{"post":{"summary":"Send one SMS","operationId":"sendMessage","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SingleSendIn"},"example":{"to":"08031234567","from":"ACME","body":"Your ACME code is 482913. It expires in 5 minutes.","client_reference":"order-78123"}}},"required":true},"responses":{"202":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"},"Location":{"$ref":"#/components/headers/Location"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageEnvelope"},"example":{"data":{"id":"msg_01M3KR6CEGVQVV5PV6Q9J1G6SP","object":"message","mode":"live","channel":"sms","direction":"outbound","status":"queued","to":"+2348031234567","from":"ACME","body":"Your ACME code is 482913. It expires in 5 minutes.","encoding":"gsm7","segments":1,"held_amount":"3.5000","unit_price":null,"amount":null,"currency":"NGN","client_reference":"order-78123","campaign_id":null,"source":"api","error":null,"scheduled_at":null,"created_at":"2026-09-28T10:15:30.000Z","sent_at":null,"completed_at":null,"updated_at":"2026-09-28T10:15:30.000Z"}}}}},"401":{"description":"unauthenticated","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"value":{"type":"https://docs.messaging.500calls.com/errors/unauthenticated","title":"Authentication required","status":401,"code":"unauthenticated","detail":"Send a valid API key in the header 'Authorization: Bearer <key>'.","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"402":{"description":"insufficient_balance","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"insufficient_balance":{"value":{"type":"https://docs.messaging.500calls.com/errors/insufficient_balance","title":"Insufficient balance","status":402,"code":"insufficient_balance","detail":"This request needs a hold of NGN 3.5000 but your available balance is NGN 1.2000. No messages were accepted.","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[],"required_amount":"3.5000","available_amount":"1.2000","currency":"NGN"}}}}}},"403":{"description":"ip_not_allowed, insufficient_scope, email_not_verified, tenant_suspended","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ip_not_allowed":{"value":{"type":"https://docs.messaging.500calls.com/errors/ip_not_allowed","title":"IP address not allowed","status":403,"code":"ip_not_allowed","detail":"IP address not allowed","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}},"insufficient_scope":{"value":{"type":"https://docs.messaging.500calls.com/errors/insufficient_scope","title":"Insufficient scope","status":403,"code":"insufficient_scope","detail":"This API key does not have the messages:send scope.","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}},"email_not_verified":{"value":{"type":"https://docs.messaging.500calls.com/errors/email_not_verified","title":"Email address not verified","status":403,"code":"email_not_verified","detail":"Email address not verified","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}},"tenant_suspended":{"value":{"type":"https://docs.messaging.500calls.com/errors/tenant_suspended","title":"Account suspended","status":403,"code":"tenant_suspended","detail":"Your account is suspended; sending is paused.","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"409":{"description":"conflict, idempotency_key_reused","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"conflict":{"value":{"type":"https://docs.messaging.500calls.com/errors/conflict","title":"Conflict","status":409,"code":"conflict","detail":"A request with this Idempotency-Key is in progress.","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}},"idempotency_key_reused":{"value":{"type":"https://docs.messaging.500calls.com/errors/idempotency_key_reused","title":"Idempotency key reused","status":409,"code":"idempotency_key_reused","detail":"This Idempotency-Key was already used with a different request body.","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"413":{"description":"payload_too_large","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"payload_too_large":{"value":{"type":"https://docs.messaging.500calls.com/errors/payload_too_large","title":"Payload too large","status":413,"code":"payload_too_large","detail":"Payload too large","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"415":{"description":"unsupported_media_type","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unsupported_media_type":{"value":{"type":"https://docs.messaging.500calls.com/errors/unsupported_media_type","title":"Unsupported media type","status":415,"code":"unsupported_media_type","detail":"Unsupported media type","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"422":{"description":"validation_error, sender_id_not_approved","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_error":{"value":{"type":"https://docs.messaging.500calls.com/errors/validation_error","title":"Validation error","status":422,"code":"validation_error","detail":"No recipient could be accepted. No message was created.","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[{"field":"to","code":"invalid_recipient","message":"Not a valid mobile number."}]}},"sender_id_not_approved":{"value":{"type":"https://docs.messaging.500calls.com/errors/sender_id_not_approved","title":"Sender ID not approved","status":422,"code":"sender_id_not_approved","detail":"Sender ID not approved","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"429":{"description":"rate_limited","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"value":{"type":"https://docs.messaging.500calls.com/errors/rate_limited","title":"Too many requests","status":429,"code":"rate_limited","detail":"quota_exceeded:public_api_rate","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"500":{"description":"internal_error","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal_error":{"value":{"type":"https://docs.messaging.500calls.com/errors/internal_error","title":"Internal error","status":500,"code":"internal_error","detail":"Internal error","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"503":{"description":"service_unavailable","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"service_unavailable":{"value":{"type":"https://docs.messaging.500calls.com/errors/service_unavailable","title":"Service unavailable","status":503,"code":"service_unavailable","detail":"Service unavailable","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}}},"tags":["Sending"],"security":[{"bearerAuth":["messages:send"]}],"description":"Accepts one message and holds its maximum cost from your wallet. A 202 means accepted, not sent: read the message's `status` to follow it. Add `send_at` to schedule it between 1 minute and 90 days ahead, and an `Idempotency-Key` to retry safely.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"1 to 64 characters from A-Z, a-z, 0-9, `_` and `-`. Repeating a request with the same key and body within 24 hours returns the stored success response without acting again; the same key with a different body is refused with 409.","schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,64}$"},"example":"order-78123-otp"}]}},"/v1/sms/messages/batch":{"post":{"summary":"Send a personalised batch","operationId":"sendBatch","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchSendIn"},"example":{"from":"ACME","messages":[{"to":"08031234567","body":"Hello Ada, your balance is ₦12,500.00.","client_reference":"acct-1001"},{"to":"08129876543","body":"Hello Chinedu, your balance is ₦3,200.00.","client_reference":"acct-1002"}]}}},"required":true},"responses":{"202":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendResultEnvelope"},"example":{"data":{"object":"send_result","mode":"live","reservation_id":"rsv_01M3KR6CZMBP3APZFHRGEMMMYE","requested":5,"accepted":2,"rejected":3,"segments":2,"held_amount":"5.8000","currency":"NGN","messages":[{"index":0,"input":"08031234567","to":"+2348031234567","id":"msg_01M3KR6D868QPH5MEE2236DZS0","status":"queued","segments":1,"held_amount":"2.9000","client_reference":null,"error":null},{"index":1,"input":"+2348059876543","to":"+2348059876543","id":"msg_01M3KR6D868QPH5MEE2236DZS1","status":"queued","segments":1,"held_amount":"2.9000","client_reference":null,"error":null},{"index":2,"input":"0803 123 4567","to":"+2348031234567","id":"msg_01M3KR6D868QPH5MEE2236DZS2","status":"rejected","segments":1,"held_amount":"0.0000","client_reference":null,"error":{"code":"duplicate_recipient","message":"The same number appears earlier in this request."}},{"index":3,"input":"12345","to":"12345","id":"msg_01M3KR6D868QPH5MEE2236DZS3","status":"rejected","segments":1,"held_amount":"0.0000","client_reference":null,"error":{"code":"invalid_recipient","message":"Not a valid mobile number."}},{"index":4,"input":"+447700900123","to":"+447700900123","id":"msg_01M3KR6D868QPH5MEE2236DZS4","status":"rejected","segments":1,"held_amount":"0.0000","client_reference":null,"error":{"code":"destination_not_supported","message":"The destination country is not enabled."}}]}}}}},"401":{"description":"unauthenticated","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"value":{"type":"https://docs.messaging.500calls.com/errors/unauthenticated","title":"Authentication required","status":401,"code":"unauthenticated","detail":"Send a valid API key in the header 'Authorization: Bearer <key>'.","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"402":{"description":"insufficient_balance","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"insufficient_balance":{"value":{"type":"https://docs.messaging.500calls.com/errors/insufficient_balance","title":"Insufficient balance","status":402,"code":"insufficient_balance","detail":"This request needs a hold of NGN 3.5000 but your available balance is NGN 1.2000. No messages were accepted.","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[],"required_amount":"3.5000","available_amount":"1.2000","currency":"NGN"}}}}}},"403":{"description":"ip_not_allowed, insufficient_scope, email_not_verified, tenant_suspended","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ip_not_allowed":{"value":{"type":"https://docs.messaging.500calls.com/errors/ip_not_allowed","title":"IP address not allowed","status":403,"code":"ip_not_allowed","detail":"IP address not allowed","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}},"insufficient_scope":{"value":{"type":"https://docs.messaging.500calls.com/errors/insufficient_scope","title":"Insufficient scope","status":403,"code":"insufficient_scope","detail":"This API key does not have the messages:send scope.","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}},"email_not_verified":{"value":{"type":"https://docs.messaging.500calls.com/errors/email_not_verified","title":"Email address not verified","status":403,"code":"email_not_verified","detail":"Email address not verified","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}},"tenant_suspended":{"value":{"type":"https://docs.messaging.500calls.com/errors/tenant_suspended","title":"Account suspended","status":403,"code":"tenant_suspended","detail":"Your account is suspended; sending is paused.","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"409":{"description":"conflict, idempotency_key_reused","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"conflict":{"value":{"type":"https://docs.messaging.500calls.com/errors/conflict","title":"Conflict","status":409,"code":"conflict","detail":"A request with this Idempotency-Key is in progress.","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}},"idempotency_key_reused":{"value":{"type":"https://docs.messaging.500calls.com/errors/idempotency_key_reused","title":"Idempotency key reused","status":409,"code":"idempotency_key_reused","detail":"This Idempotency-Key was already used with a different request body.","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"413":{"description":"payload_too_large","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"payload_too_large":{"value":{"type":"https://docs.messaging.500calls.com/errors/payload_too_large","title":"Payload too large","status":413,"code":"payload_too_large","detail":"Payload too large","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"415":{"description":"unsupported_media_type","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unsupported_media_type":{"value":{"type":"https://docs.messaging.500calls.com/errors/unsupported_media_type","title":"Unsupported media type","status":415,"code":"unsupported_media_type","detail":"Unsupported media type","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"422":{"description":"validation_error, sender_id_not_approved, too_many_recipients","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_error":{"value":{"type":"https://docs.messaging.500calls.com/errors/validation_error","title":"Validation error","status":422,"code":"validation_error","detail":"No recipient could be accepted. No messages were created.","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[{"field":"messages[0].to","code":"invalid_recipient","message":"Not a valid mobile number."},{"field":"messages[1].body","code":"body_too_long","message":"The message is longer than 10 segments."}]}},"sender_id_not_approved":{"value":{"type":"https://docs.messaging.500calls.com/errors/sender_id_not_approved","title":"Sender ID not approved","status":422,"code":"sender_id_not_approved","detail":"Sender ID not approved","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}},"too_many_recipients":{"value":{"type":"https://docs.messaging.500calls.com/errors/too_many_recipients","title":"Too many recipients","status":422,"code":"too_many_recipients","detail":"This request has 1,200 recipients; the maximum is 1,000.","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[],"limit":1000}}}}}},"429":{"description":"rate_limited","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"value":{"type":"https://docs.messaging.500calls.com/errors/rate_limited","title":"Too many requests","status":429,"code":"rate_limited","detail":"quota_exceeded:public_api_rate","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"500":{"description":"internal_error","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal_error":{"value":{"type":"https://docs.messaging.500calls.com/errors/internal_error","title":"Internal error","status":500,"code":"internal_error","detail":"Internal error","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"503":{"description":"service_unavailable","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"service_unavailable":{"value":{"type":"https://docs.messaging.500calls.com/errors/service_unavailable","title":"Service unavailable","status":503,"code":"service_unavailable","detail":"Service unavailable","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}}},"tags":["Sending"],"security":[{"bearerAuth":["messages:send"]}],"description":"Sends one message per item, each with its own recipient and body, from one sender ID. Bodies are sent exactly as given. Per-item outcomes, the 422 and the 402 follow the bulk send.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"1 to 64 characters from A-Z, a-z, 0-9, `_` and `-`. Repeating a request with the same key and body within 24 hours returns the stored success response without acting again; the same key with a different body is refused with 409.","schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,64}$"},"example":"order-78123-otp"}]}},"/v1/sms/messages/bulk":{"post":{"summary":"Send one SMS to many recipients","operationId":"sendBulk","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkSendIn"},"example":{"to":["08031234567","+2348059876543","0803 123 4567","12345","+447700900123"],"from":"ACMESTORES","body":"Hi! Our Lekki store opens at 9am tomorrow."}}},"required":true},"responses":{"202":{"description":"Success","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendResultEnvelope"},"example":{"data":{"object":"send_result","mode":"live","reservation_id":"rsv_01M3KR6CZMBP3APZFHRGEMMMYE","requested":5,"accepted":2,"rejected":3,"segments":2,"held_amount":"5.8000","currency":"NGN","messages":[{"index":0,"input":"08031234567","to":"+2348031234567","id":"msg_01M3KR6D868QPH5MEE2236DZS0","status":"queued","segments":1,"held_amount":"2.9000","client_reference":null,"error":null},{"index":1,"input":"+2348059876543","to":"+2348059876543","id":"msg_01M3KR6D868QPH5MEE2236DZS1","status":"queued","segments":1,"held_amount":"2.9000","client_reference":null,"error":null},{"index":2,"input":"0803 123 4567","to":"+2348031234567","id":"msg_01M3KR6D868QPH5MEE2236DZS2","status":"rejected","segments":1,"held_amount":"0.0000","client_reference":null,"error":{"code":"duplicate_recipient","message":"The same number appears earlier in this request."}},{"index":3,"input":"12345","to":"12345","id":"msg_01M3KR6D868QPH5MEE2236DZS3","status":"rejected","segments":1,"held_amount":"0.0000","client_reference":null,"error":{"code":"invalid_recipient","message":"Not a valid mobile number."}},{"index":4,"input":"+447700900123","to":"+447700900123","id":"msg_01M3KR6D868QPH5MEE2236DZS4","status":"rejected","segments":1,"held_amount":"0.0000","client_reference":null,"error":{"code":"destination_not_supported","message":"The destination country is not enabled."}}]}}}}},"401":{"description":"unauthenticated","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"value":{"type":"https://docs.messaging.500calls.com/errors/unauthenticated","title":"Authentication required","status":401,"code":"unauthenticated","detail":"Send a valid API key in the header 'Authorization: Bearer <key>'.","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"402":{"description":"insufficient_balance","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"insufficient_balance":{"value":{"type":"https://docs.messaging.500calls.com/errors/insufficient_balance","title":"Insufficient balance","status":402,"code":"insufficient_balance","detail":"This request needs a hold of NGN 3.5000 but your available balance is NGN 1.2000. No messages were accepted.","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[],"required_amount":"3.5000","available_amount":"1.2000","currency":"NGN"}}}}}},"403":{"description":"ip_not_allowed, insufficient_scope, email_not_verified, tenant_suspended","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ip_not_allowed":{"value":{"type":"https://docs.messaging.500calls.com/errors/ip_not_allowed","title":"IP address not allowed","status":403,"code":"ip_not_allowed","detail":"IP address not allowed","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}},"insufficient_scope":{"value":{"type":"https://docs.messaging.500calls.com/errors/insufficient_scope","title":"Insufficient scope","status":403,"code":"insufficient_scope","detail":"This API key does not have the messages:send scope.","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}},"email_not_verified":{"value":{"type":"https://docs.messaging.500calls.com/errors/email_not_verified","title":"Email address not verified","status":403,"code":"email_not_verified","detail":"Email address not verified","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}},"tenant_suspended":{"value":{"type":"https://docs.messaging.500calls.com/errors/tenant_suspended","title":"Account suspended","status":403,"code":"tenant_suspended","detail":"Your account is suspended; sending is paused.","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"409":{"description":"conflict, idempotency_key_reused","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"conflict":{"value":{"type":"https://docs.messaging.500calls.com/errors/conflict","title":"Conflict","status":409,"code":"conflict","detail":"A request with this Idempotency-Key is in progress.","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}},"idempotency_key_reused":{"value":{"type":"https://docs.messaging.500calls.com/errors/idempotency_key_reused","title":"Idempotency key reused","status":409,"code":"idempotency_key_reused","detail":"This Idempotency-Key was already used with a different request body.","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"413":{"description":"payload_too_large","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"payload_too_large":{"value":{"type":"https://docs.messaging.500calls.com/errors/payload_too_large","title":"Payload too large","status":413,"code":"payload_too_large","detail":"Payload too large","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"415":{"description":"unsupported_media_type","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unsupported_media_type":{"value":{"type":"https://docs.messaging.500calls.com/errors/unsupported_media_type","title":"Unsupported media type","status":415,"code":"unsupported_media_type","detail":"Unsupported media type","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"422":{"description":"validation_error, sender_id_not_approved, too_many_recipients","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_error":{"value":{"type":"https://docs.messaging.500calls.com/errors/validation_error","title":"Validation error","status":422,"code":"validation_error","detail":"No recipient could be accepted. No messages were created.","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[{"field":"to[0]","code":"invalid_recipient","message":"Not a valid mobile number."},{"field":"to[1]","code":"invalid_recipient","message":"Not a valid mobile number."}]}},"sender_id_not_approved":{"value":{"type":"https://docs.messaging.500calls.com/errors/sender_id_not_approved","title":"Sender ID not approved","status":422,"code":"sender_id_not_approved","detail":"Sender ID not approved","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}},"too_many_recipients":{"value":{"type":"https://docs.messaging.500calls.com/errors/too_many_recipients","title":"Too many recipients","status":422,"code":"too_many_recipients","detail":"This request has 1,200 recipients; the maximum is 1,000.","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[],"limit":1000}}}}}},"429":{"description":"rate_limited","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"value":{"type":"https://docs.messaging.500calls.com/errors/rate_limited","title":"Too many requests","status":429,"code":"rate_limited","detail":"quota_exceeded:public_api_rate","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"500":{"description":"internal_error","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal_error":{"value":{"type":"https://docs.messaging.500calls.com/errors/internal_error","title":"Internal error","status":500,"code":"internal_error","detail":"Internal error","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}},"503":{"description":"service_unavailable","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"service_unavailable":{"value":{"type":"https://docs.messaging.500calls.com/errors/service_unavailable","title":"Service unavailable","status":503,"code":"service_unavailable","detail":"Service unavailable","request_id":"req_01M3KR6CQ26S90NG2V790GVFTX","errors":[]}}}}}}},"tags":["Sending"],"security":[{"bearerAuth":["messages:send"]}],"description":"Sends the same body to every recipient in `to`, up to the per-request limit (1,000 by default). Each recipient is checked on its own: one that fails is created as `rejected` with its error and the others go ahead. If none passes, the request is refused with 422 and nothing is created. If the held total exceeds your available balance, nothing is accepted (402).","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"1 to 64 characters from A-Z, a-z, 0-9, `_` and `-`. Repeating a request with the same key and body within 24 hours returns the stored success response without acting again; the same key with a different body is refused with 409.","schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,64}$"},"example":"order-78123-otp"}]}}},"components":{"schemas":{"Balance":{"type":"object","required":["as_of","available","balance","currency","held","low_balance_threshold","object"],"properties":{"object":{"type":"string","const":"balance","description":"Always `balance`."},"currency":{"type":"string","const":"NGN","description":"Always `NGN`."},"balance":{"type":"string","pattern":"^\\d+\\.\\d{4}$","description":"All the money in your wallet, including what is held for messages in flight."},"held":{"type":"string","pattern":"^\\d+\\.\\d{4}$","description":"Money held for messages that are scheduled, queued or being sent, and for finished messages until they are settled, within about a minute."},"available":{"type":"string","pattern":"^\\d+\\.\\d{4}$","description":"What new sends can use: `balance` minus `held`."},"low_balance_threshold":{"type":"string","pattern":"^\\d+\\.\\d{4}$","description":"Your low-balance alert threshold."},"as_of":{"type":"string","format":"date-time","description":"When the balance was read."}}},"BalanceEnvelope":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Balance","description":"The balance."}}},"BatchItemIn":{"additionalProperties":false,"properties":{"to":{"maxLength":256,"title":"To","type":"string","description":"The recipient, in any common Nigerian or international format, such as `08031234567` or `+2348031234567`."},"body":{"title":"Body","type":"string","description":"This recipient's message text, sent exactly as given."},"client_reference":{"anyOf":[{"maxLength":64,"minLength":1,"pattern":"^[\\x20-\\x7e]+$","type":"string"},{"type":"null"}],"default":null,"title":"Client Reference","description":"Your own reference: 1 to 64 printable ASCII characters."}},"required":["to","body"],"title":"BatchItemIn","type":"object","description":"One message of a batch."},"BatchSendIn":{"additionalProperties":false,"description":"One sender ID and one optional `send_at` for every item; each item has its own recipient and body.","properties":{"from":{"maxLength":11,"minLength":3,"pattern":"^[A-Za-z0-9 .-]+$","title":"From","type":"string","description":"The sender ID: 3 to 11 letters, digits, spaces, hyphens or periods. It must be one of yours that can be used now."},"messages":{"items":{"$ref":"#/components/schemas/BatchItemIn"},"minItems":1,"title":"Messages","type":"array","description":"One item per message, up to the per-request limit (1,000 by default)."},"send_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Send At","description":"Schedule the send for this time, between 1 minute and 90 days from now. Omit it to send now."}},"required":["from","messages"],"title":"BatchSendIn","type":"object"},"BulkSendIn":{"additionalProperties":false,"properties":{"to":{"items":{"maxLength":256,"type":"string"},"minItems":1,"title":"To","type":"array","description":"The recipients, up to the per-request limit (1,000 by default), each in any common Nigerian or international format."},"from":{"maxLength":11,"minLength":3,"pattern":"^[A-Za-z0-9 .-]+$","title":"From","type":"string","description":"The sender ID: 3 to 11 letters, digits, spaces, hyphens or periods. It must be one of yours that can be used now."},"body":{"title":"Body","type":"string","description":"The message text sent to every recipient, exactly as given."},"client_reference":{"anyOf":[{"maxLength":64,"minLength":1,"pattern":"^[\\x20-\\x7e]+$","type":"string"},{"type":"null"}],"default":null,"title":"Client Reference","description":"Your own reference, copied onto every message created."},"send_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Send At","description":"Schedule the send for this time, between 1 minute and 90 days from now. Omit it to send now."}},"required":["to","from","body"],"title":"BulkSendIn","type":"object","description":"One body sent to every recipient in `to`."},"Error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"A stable code for what went wrong. Branch on it, never on `message`."},"message":{"type":"string","description":"A human explanation of the code."}}},"FieldError":{"type":"object","required":["code","field","message"],"properties":{"field":{"type":"string","description":"The member that failed, as a path such as `to`, `to[3]` or `messages[3].to`, or a header or query parameter name."},"code":{"type":"string","description":"A stable code for the failure, such as `required` or `invalid_recipient`. Treat a code you do not know as a generic validation failure."},"message":{"type":"string","description":"A human explanation for this field."}}},"Message":{"type":"object","required":["amount","body","campaign_id","channel","client_reference","completed_at","created_at","currency","direction","encoding","error","from","held_amount","id","mode","object","scheduled_at","segments","sent_at","source","status","to","unit_price","updated_at"],"properties":{"id":{"type":"string","pattern":"^msg_[0-9A-HJKMNP-TV-Z]{26}$","description":"The message ID: `msg_` followed by 26 characters."},"object":{"type":"string","const":"message","description":"Always `message`."},"mode":{"type":"string","enum":["live","test"],"description":"`live` for a live key. Always `live` today: test keys are not available yet."},"channel":{"type":"string","enum":["sms"],"description":"Always `sms`."},"direction":{"type":"string","enum":["outbound"],"description":"Always `outbound`."},"status":{"type":"string","enum":["scheduled","queued","sent","delivered","undelivered","expired","rejected","failed","cancelled"],"x-closed-enum":true,"description":"Where the message is now. `scheduled`, `queued` and `sent` are in progress. `delivered`, `undelivered`, `expired`, `rejected`, `failed` and `cancelled` are final, and `completed_at` is set when the message reaches one. A late delivery receipt can still move an `undelivered` or `expired` message to `delivered`, and an `expired` one to `undelivered`."},"to":{"type":"string","description":"The recipient in E.164 format; the value you sent when it could not be read."},"from":{"type":"string","description":"The sender ID the message is sent from."},"body":{"type":"string","description":"The message text, exactly as sent."},"encoding":{"type":"string","enum":["gsm7","ucs2"],"description":"`gsm7`, or `ucs2` when the body has a character outside the GSM 7-bit alphabet, such as the naira sign."},"segments":{"type":"integer","minimum":1,"description":"How many SMS parts the body takes, from 1 to 10. Prices are per segment."},"held_amount":{"type":"string","pattern":"^\\d+\\.\\d{4}$","description":"The most this message can cost, held from your balance when it was accepted; `0.0000` for a rejected message."},"unit_price":{"anyOf":[{"type":"string","pattern":"^\\d+\\.\\d{4}$"},{"type":"null"}],"description":"The price per segment of the route that carried the message; `null` until it is sent."},"amount":{"anyOf":[{"type":"string","pattern":"^\\d+\\.\\d{4}$"},{"type":"null"}],"description":"What you were charged: the segments times `unit_price`, never more than `held_amount`. `null` until the message is sent; `0.0000` when it was rejected, failed or cancelled."},"currency":{"type":"string","const":"NGN","description":"Always `NGN`. Amounts are strings with four decimal places."},"client_reference":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Your own reference for the message, as you sent it."},"campaign_id":{"anyOf":[{"type":"string","pattern":"^cmp_[0-9A-HJKMNP-TV-Z]{26}$"},{"type":"null"}],"description":"The campaign the message belongs to, for messages sent from the dashboard."},"source":{"type":"string","enum":["api","campaign","quick_send","test_send"],"description":"How the message was sent: `api`, `campaign`, `quick_send` or `test_send`."},"error":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"type":"null"}],"description":"Why the message was rejected, failed, cancelled, undelivered or expired; otherwise `null`."},"scheduled_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"The `send_at` time you asked for; `null` when you sent it straight away."},"created_at":{"type":"string","format":"date-time","description":"When the message was accepted."},"sent_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"When a route accepted the message; `null` before that."},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"When the message reached its current final status; `null` before that."},"updated_at":{"type":"string","format":"date-time","description":"When the message last changed."}}},"MessageEnvelope":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Message","description":"The message."}}},"MessageHistoryEntry":{"type":"object","required":["error","occurred_at","status"],"properties":{"status":{"type":"string","enum":["scheduled","queued","sent","delivered","undelivered","expired","rejected","failed","cancelled"],"x-closed-enum":true,"description":"The status the message moved to."},"occurred_at":{"type":"string","format":"date-time","description":"When it moved."},"error":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"type":"null"}],"description":"Why, for a rejected, failed, cancelled, undelivered or expired status; otherwise `null`."}}},"MessageList":{"type":"object","required":["data","next_cursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Message"},"description":"The messages on this page, newest first."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Pass this back as `cursor` for the next page; `null` on the last page."}}},"MessageWithHistory":{"allOf":[{"$ref":"#/components/schemas/Message"},{"type":"object","required":["status_history"],"properties":{"status_history":{"type":"array","items":{"$ref":"#/components/schemas/MessageHistoryEntry"},"description":"Every status the message has had, oldest first."}}}]},"MessageWithHistoryEnvelope":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/MessageWithHistory","description":"The message with its status history."}}},"Problem":{"type":"object","required":["code","detail","errors","request_id","status","title","type"],"properties":{"type":{"type":"string","description":"A link to this error code's documentation page."},"title":{"type":"string","description":"A short summary of the code. It never changes for a code."},"status":{"type":"integer","description":"The HTTP status code."},"code":{"type":"string","enum":["conflict","email_not_verified","idempotency_key_reused","insufficient_balance","insufficient_scope","internal_error","invalid_state_transition","ip_not_allowed","not_found","payload_too_large","rate_limited","sender_id_not_approved","service_unavailable","tenant_suspended","too_many_recipients","unauthenticated","unsupported_media_type","validation_error"],"description":"A stable code for the error. Branch on it, never on `title` or `detail`."},"detail":{"type":"string","description":"A human explanation of this occurrence."},"request_id":{"type":"string","pattern":"^req_[0-9A-HJKMNP-TV-Z]{26}$","description":"This request's ID, also sent as `X-Request-Id`. Quote it to support."},"errors":{"type":"array","items":{"$ref":"#/components/schemas/FieldError"},"description":"The fields that failed, for a validation error; otherwise empty."}}},"SendResult":{"type":"object","required":["accepted","currency","held_amount","messages","mode","object","rejected","requested","reservation_id","segments"],"properties":{"object":{"type":"string","const":"send_result","description":"Always `send_result`."},"mode":{"type":"string","enum":["live","test"],"description":"`live` for a live key. Always `live` today: test keys are not available yet."},"reservation_id":{"type":"string","pattern":"^rsv_[0-9A-HJKMNP-TV-Z]{26}$","description":"The ID of the hold that covers this request's accepted messages."},"requested":{"type":"integer","minimum":1,"description":"How many recipients or items the request had."},"accepted":{"type":"integer","minimum":1,"description":"How many messages were accepted, as `queued` or `scheduled`."},"rejected":{"type":"integer","minimum":0,"description":"How many messages were created as `rejected`."},"segments":{"type":"integer","minimum":1,"description":"The total segments of the accepted messages."},"held_amount":{"type":"string","pattern":"^\\d+\\.\\d{4}$","description":"The total held for the accepted messages: the most this request can cost."},"currency":{"type":"string","const":"NGN","description":"Always `NGN`."},"messages":{"type":"array","items":{"$ref":"#/components/schemas/SendResultEntry"},"description":"One entry per recipient or item, in the order you sent them."}}},"SendResultEntry":{"type":"object","required":["client_reference","error","held_amount","id","index","input","segments","status","to"],"properties":{"index":{"type":"integer","minimum":0,"description":"This entry's position in your request, from 0."},"input":{"type":"string","description":"The recipient exactly as you sent it."},"to":{"type":"string","description":"The recipient in E.164 format; the value you sent when it could not be read."},"id":{"type":"string","pattern":"^msg_[0-9A-HJKMNP-TV-Z]{26}$","description":"The message ID, for accepted and rejected messages alike."},"status":{"type":"string","enum":["scheduled","queued","rejected"],"x-closed-enum":true,"description":"`queued`, `scheduled` or `rejected`."},"segments":{"type":"integer","minimum":1,"description":"The segments this message takes."},"held_amount":{"type":"string","pattern":"^\\d+\\.\\d{4}$","description":"The amount held for this message; `0.0000` when it was rejected."},"client_reference":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The item's reference for a batch; the request's reference for a bulk send."},"error":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"type":"null"}],"description":"Why the message was rejected; otherwise `null`."}}},"SendResultEnvelope":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/SendResult","description":"The outcome of the request."}}},"SenderId":{"type":"object","required":["created_at","decided_at","id","object","ready","status","status_reason","updated_at","usable","value"],"properties":{"object":{"type":"string","const":"sender_id","description":"Always `sender_id`."},"id":{"type":"string","pattern":"^sid_[0-9A-HJKMNP-TV-Z]{26}$","description":"The sender ID's ID: `sid_` followed by 26 characters."},"value":{"type":"string","description":"The name recipients see, such as `ACME`."},"status":{"type":"string","enum":["pending","approved","rejected","suspended","withdrawn"],"description":"`pending`, `approved`, `rejected`, `suspended` or `withdrawn`."},"ready":{"type":"boolean","description":"The same as `usable`."},"usable":{"type":"boolean","description":"`true` when you can send from it now: it is approved and active on at least one route. Approval makes it active straight away; it stops being usable if it is suspended, withdrawn or deactivated on every route."},"status_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Why it was rejected or suspended; otherwise `null`."},"created_at":{"type":"string","format":"date-time","description":"When you requested it."},"decided_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"When it was approved or rejected; `null` while pending."},"updated_at":{"type":"string","format":"date-time","description":"When it last changed."}}},"SenderIdList":{"type":"object","required":["data","next_cursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SenderId"},"description":"Your sender IDs on this page, newest first."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Pass this back as `cursor` for the next page; `null` on the last page."}}},"SingleSendIn":{"additionalProperties":false,"properties":{"to":{"maxLength":256,"title":"To","type":"string","description":"The recipient, in any common Nigerian or international format, such as `08031234567` or `+2348031234567`."},"from":{"maxLength":11,"minLength":3,"pattern":"^[A-Za-z0-9 .-]+$","title":"From","type":"string","description":"The sender ID: 3 to 11 letters, digits, spaces, hyphens or periods. It must be one of yours that can be used now."},"body":{"title":"Body","type":"string","description":"The message text, sent exactly as given. Placeholders such as `{{name}}` are not filled in; send a batch to personalise."},"client_reference":{"anyOf":[{"maxLength":64,"minLength":1,"pattern":"^[\\x20-\\x7e]+$","type":"string"},{"type":"null"}],"default":null,"title":"Client Reference","description":"Your own reference: 1 to 64 printable ASCII characters. You can filter messages by it."},"send_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Send At","description":"Schedule the send for this time, between 1 minute and 90 days from now. Omit it to send now."}},"required":["to","from","body"],"title":"SingleSendIn","type":"object","description":"One message to one recipient."}},"headers":{"XRequestId":{"description":"This request's ID, also given as `request_id` in error bodies. Quote it to support.","schema":{"type":"string","pattern":"^req_[0-9A-HJKMNP-TV-Z]{26}$"},"required":true},"CacheControl":{"description":"Responses are never cached.","schema":{"type":"string","const":"no-store"},"required":true},"RateLimitLimit":{"description":"Requests per second your account may sustain.","schema":{"type":"integer","minimum":0}},"RateLimitRemaining":{"description":"Whole requests left in your account's bucket.","schema":{"type":"integer","minimum":0}},"RateLimitReset":{"description":"Seconds until the bucket is full again.","schema":{"type":"integer","minimum":0}},"RetryAfter":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1},"required":true},"IdempotentReplayed":{"description":"Present when this is the stored response of an earlier request with the same Idempotency-Key.","schema":{"type":"string","const":"true"}},"Location":{"description":"The new message's URL, `/v1/messages/{id}`.","schema":{"type":"string"},"required":true}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"An API key, `500c_live_…`, sent as `Authorization: Bearer <key>`. Each operation names the scope its key needs. Test keys (`500c_test_…`) are not available yet."}}},"security":[{"bearerAuth":[]}]}