Quickstart

This guide gets you from zero to your first authenticated API request. We'll create an API key, list the main numbers on your account, and point you at the resource pages once you're up and running.

Create an API key

1. Sign in to your Phone.inc dashboard at https://app.phone.inc.
2. Open Your account → API Keys, or go directly to https://app.phone.inc/api_keys.
3. Click Create API key, name it (e.g. Local development), and copy the token. It's shown to you exactly once — store it somewhere safe.

Tokens look like phk_a1B2c3D4e5F6g7H8j9K1m2N3p4Q5r6S7. Set it as an environment variable so you can paste the snippets below directly:

export PHONE_INC_API_KEY="phk_a1B2c3D4e5F6g7H8j9K1m2N3p4Q5r6S7"

For the full key lifecycle — rotation, revocation, security — see Authentication.

Make your first request

Hit the main_numbers endpoint to fetch every phone number on your account. It's the simplest call and a good way to confirm your key works.

curl https://app.phone.inc/api/v1/main_numbers \
  -H "X-Api-Key: $PHONE_INC_API_KEY"

You'll get back something like:

{
  "main_numbers": [
    {
      "id": "0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01",
      "name": "Sales",
      "number": "+14155551234",
      "number_formatted": "+1 415-555-1234"
    },
    {
      "id": "0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c02",
      "name": "Support",
      "number": "+14155555678",
      "number_formatted": "+1 415-555-5678"
    }
  ]
}

If you see a 401 Invalid API key, double-check the value of $PHONE_INC_API_KEY and confirm the key still exists at app.phone.inc/api_keys.

Where to go next

You're authenticated and the API is responding. Pick what you need:

• Main Numbers — list the phone numbers on your account.
• Calls — list and inspect inbound and outbound calls, filter by phone number, direction, or state.
• Voicemails — fetch voicemail recordings and mark them as listened.
• Caller context — look up customer context (Shopify orders today) for an inbound caller.

When something goes wrong, check the Errors page for the response shape and how to handle it.