> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tracklysms.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List Number Requests

> Retrieve account-owned number provisioning requests, newest first.

Returns number requests for the API-key account, ordered newest first and paginated. Read operations work with live and sandbox keys.

The response contains only request-owned fields. It does not include `businessProfileId`, provider object ids, private attachment paths, or the carrier identifier value in `taxId`.

## Query parameters

<ParamField query="page" type="integer" optional default="1">
  Page number.
</ParamField>

<ParamField query="per_page" type="integer" optional default="50">
  Items per page, from 1 through 100.
</ParamField>

## Response

<ResponseField name="pagination" type="object">
  Contains `page`, `per_page`, `total`, and `total_pages`.
</ResponseField>

<ResponseField name="requests" type="array">
  Account-owned number request objects.

  <Expandable title="Number request fields">
    <ResponseField name="id" type="string">
      Number request id.
    </ResponseField>

    <ResponseField name="brandName" type="string">
      Brand name.
    </ResponseField>

    <ResponseField name="companyLegalName" type="string">
      Request-owned registered legal name.
    </ResponseField>

    <ResponseField name="listName" type="string">
      Sending list name.
    </ResponseField>

    <ResponseField name="phoneNumberType" type="string">
      `toll_free` or `10dlc`.
    </ResponseField>

    <ResponseField name="messagingType" type="string">
      Messaging use case.
    </ResponseField>

    <ResponseField name="vertical" type="string">
      TCR vertical when present.
    </ResponseField>

    <ResponseField name="targetCountries" type="array">
      Exactly one number country for new requests.
    </ResponseField>

    <ResponseField name="websiteUrl" type="string">
      Business website.
    </ResponseField>

    <ResponseField name="optInFormUrl" type="string">
      Customer-hosted opt-in URL.
    </ResponseField>

    <ResponseField name="termsConditionsUrl" type="string">
      Terms and Conditions URL when supplied.
    </ResponseField>

    <ResponseField name="contactEmail" type="string">
      Carrier support email.
    </ResponseField>

    <ResponseField name="contactPhone" type="string">
      Carrier support phone.
    </ResponseField>

    <ResponseField name="businessContactFirstName" type="string">
      Authorized carrier contact first name.
    </ResponseField>

    <ResponseField name="businessContactLastName" type="string">
      Authorized carrier contact last name.
    </ResponseField>

    <ResponseField name="industry" type="string">
      Business industry.
    </ResponseField>

    <ResponseField name="addressStreet" type="string">
      Business street.
    </ResponseField>

    <ResponseField name="addressCity" type="string">
      Business city.
    </ResponseField>

    <ResponseField name="addressState" type="string">
      Business state or province.
    </ResponseField>

    <ResponseField name="addressPostalCode" type="string">
      Business postal code.
    </ResponseField>

    <ResponseField name="addressCountry" type="string">
      Business address country that selected the carrier identifier.
    </ResponseField>

    <ResponseField name="identifierType" type="string">
      Canonical request identifier type. The identifier value is not returned.
    </ResponseField>

    <ResponseField name="estimatedMonthlyVolume" type="string">
      Estimated monthly segment volume.
    </ResponseField>

    <ResponseField name="status" type="string">
      Request lifecycle status, such as `draft`, `pending`, `approved`, or `rejected`.
    </ResponseField>

    <ResponseField name="provisioningStatus" type="string">
      Provider provisioning status: `not_started`, `in_progress`, `completed`, or `failed`.
    </ResponseField>

    <ResponseField name="provisionedPhoneNumber" type="string">
      Provisioned E.164 number when available.
    </ResponseField>

    <ResponseField name="campaignStage" type="string">
      USA carrier campaign stage when applicable.
    </ResponseField>

    <ResponseField name="rejectionReason" type="string">
      Safe rejection reason when present.
    </ResponseField>

    <ResponseField name="internationalAcquisitionStatus" type="string">
      Resource Request status for CA or another non-US target.
    </ResponseField>

    <ResponseField name="internationalAcquisitionFeedback" type="object">
      Safe provider feedback keyed by requirement.
    </ResponseField>

    <ResponseField name="internationalAcquisitionFormData" type="object">
      Persisted request-owned dynamic form values.
    </ResponseField>

    <ResponseField name="internationalAcquisitionDocuments" type="array">
      Request-owned document metadata. Private paths and provider document ids are omitted.
    </ResponseField>

    <ResponseField name="createdAt" type="datetime">
      Creation timestamp.
    </ResponseField>

    <ResponseField name="updatedAt" type="datetime">
      Last update timestamp.
    </ResponseField>
  </Expandable>
</ResponseField>

## Example

<RequestExample>
  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.tracklysms.com/api/v2/number-requests",
      headers={"X-Api-Key": "trk_your_api_key_here"},
  )
  ```
</RequestExample>

<ResponseExample>
  ```json 200 — Success theme={null}
  {
    "requests": [
      {
        "id": "665f0a1b2c3d4e5f60718293",
        "brandName": "Acme Co",
        "companyLegalName": "Acme Incorporated",
        "listName": "Acme Alerts",
        "phoneNumberType": "toll_free",
        "targetCountries": ["CA"],
        "addressCountry": "GB",
        "identifierType": "vat",
        "status": "pending",
        "provisioningStatus": "not_started",
        "internationalAcquisitionStatus": "PENDING_REVIEW",
        "createdAt": "2026-08-03T22:00:00",
        "updatedAt": "2026-08-03T22:05:00"
      }
    ],
    "pagination": {
      "page": 1,
      "per_page": 50,
      "total": 1,
      "total_pages": 1
    }
  }
  ```
</ResponseExample>

## Error codes

| HTTP | Code                  | Meaning                        |
| ---- | --------------------- | ------------------------------ |
| 401  | `invalid_credentials` | API key is missing or invalid. |
| 403  | `account_suspended`   | Account access is suspended.   |

## Next steps

<CardGroup cols={2}>
  <Card title="Get Number Request" icon="magnifying-glass" href="/api-reference/v2/number-requests/get-request">
    Read one request
  </Card>

  <Card title="Create Number Request" icon="plus" href="/api-reference/v2/number-requests/create-request">
    Submit a new request-owned identity
  </Card>
</CardGroup>