Phonekit

Docs

The Phonekit API

Everything a number receives is available over HTTP and webhooks. The API reads; numbers are claimed and released in the workspace.

AuthenticationNumbersMessagesWebhooks

Authentication

Every request carries an API key created in Settings → Automation. A key belongs to one organization and can read only its explicitly selected numbers.

The key is shown once, when you create it. Lost keys are revoked and replaced, not recovered. Creating and revoking a key is written to your organization’s history.

Request
GET /api/v1/numbers
Authorization: Bearer pk_…

Numbers

  • GET /api/v1/numbersThe numbers explicitly selected for this key, with label, type and status.
  • GET /api/v1/numbers?numberId=:idOne number within the key’s selected scope.

Numbers are claimed and released in the workspace, not over the API.

Messages

  • GET /api/v1/messagesMessages across the numbers in the organization, newest first.
  • ?numberId=<id>Narrow to one number.
  • ?before=<ts>Retrieve the next page before a timestamp; up to 100 messages per page.

Detected codes

When a message looks like a verification code, the parsed code appears on a otp field alongside the untouched body. The body is never edited. If no code is detected, it is still in the text.

Reads through the API are recorded in your organization’s history, attributed to the key that made them.

Webhooks

Point Phonekit at an HTTPS endpoint to receive message.received event metadata in the shape shown on the home page. Webhooks do not contain the sender, message body or verification code.

  • Eventsmessage.received.
  • RetriesDelivery status and attempt counts are shown in organization Settings → Automation. Failed deliveries can be retried there.
  • VerificationVerify phonekit-signature using the signing secret shown when you create the webhook. phonekit-timestamp is Unix time in seconds.

Read the message

Use a read-only API key scoped to the event’s number with GET /api/v1/messages?numberId=<data.numberId> and Authorization: Bearer <API_KEY>. Find the entry whose id matches data.messageId in the response’s data array. Read its body and otp fields. Paginate with before if needed. Deleted or expired messages are no longer available; number access is limited to the key’s explicit scope.

Verify before processing

Preserve the exact raw request body before parsing JSON. Compute HMAC-SHA256 with your webhook signing secret over the timestamp header, a literal period, then the raw body bytes. Compare the lowercase hexadecimal digest with phonekit-signature using a constant-time comparison; reject missing or malformed headers and unequal lengths before comparing.

Reject timestamps outside a short tolerance (for example, five minutes) and deduplicate accepted events by id to prevent replay or repeated processing. Retries carry the same event body with a fresh timestamp and signature. Return a 2xx response after accepting the event.