Relay SMS Platform
Relay SMS API

Phone Numbers

Endpoint

Search, purchase, and manage phone numbers (Growth tier and above)

Search available phone numbers

GET
https://api.relay.works
/v1/phone-numbers/available

Search for phone numbers available to purchase. Requires Growth tier or above.

Current Status: In non-production environments this endpoint returns deterministic mock data for integration testing. Production support via a carrier provider is pending.

Search available phone numbers › query Parameters

  • area_codestring

    Filter by area code (e.g., "415")

  • containsstring

    Substring match against candidate numbers

  • localitystring

    Filter by locality/region code (e.g., "CA")

Search available phone numbers › Responses

Available phone numbers

  • numbersobject[]
  • totalinteger

List purchased phone numbers

GET
https://api.relay.works
/v1/phone-numbers

List purchased phone numbers › query Parameters

  • pageinteger · min: 1
    Default: 1
  • limitinteger · min: 1 · max: 100
    Default: 20

List purchased phone numbers › Responses

Paginated list of purchased phone numbers

  • dataobject[]
  • paginationobject

Purchase a phone number

POST
https://api.relay.works
/v1/phone-numbers/buy

Purchase a phone number for the workspace. Requires active subscription on Growth tier or higher.

Purchase a phone number › Request Body

  • phone_numberstring · required

    Phone number in E.164 format

    Example: +15005550006

Purchase a phone number › Responses

Phone number purchased

  • idstring · uuid
  • workspace_idstring · uuid
  • phone_numberstring
    Example: +15005550006
  • providerstring
    Example: mock
  • provider_idstring
  • capabilitiesobject
  • monthly_cost_centsinteger
  • currencystring
    Example: USD
  • statusstring · enum
    Enum values:
    active
    released
    pending
  • created_atstring · date-time
  • released_atstring | null · date-time
  • monthly_costnumber · float · deprecated · required

Release a phone number

DELETE
https://api.relay.works
/v1/phone-numbers/{id}

Release a phone number › path Parameters

  • idstring · uuid · required

Release a phone number › Responses

Phone number released

No data returned
API KeysWebhooks