# Authentication Learn how to gain API access. ## Prerequisites Before you begin using the OpenPhone API, ensure you have: Need an account? Follow our [account creation guide](https://support.openphone.com/hc/en-us/articles/1500009886621-How-to-create-an-OpenPhone-account). Owner or admin privileges in your OpenPhone workspace. **US Messaging Registration Required:** To send text messages to US numbers via the API, you must complete US Carrier Registration. Learn more [here](https://support.openphone.com/hc/en-us/articles/15519949741463-Guide-to-US-carrier-registration-for-OpenPhone-customers). ## API key generation The OpenPhone API uses API keys for secure authentication. Follow these steps to get started: Access your OpenPhone account. Navigate to the "API" tab under workspace settings. Remember, you need workspace owner or admin privileges to access this tab. Click "Generate API key" and provide a descriptive label. Each key provides full API access. Label your keys based on their intended use (e.g., "Production Environment" or "Testing Integration") Include your API key in the Authorization header of each request: ` Authorization: YOUR_API_KEY` The OpenPhone API does not use a Bearer token for authentication. ## Security guidelines Your API key carries the same privileges as your OpenPhone account. Treat it with the same level of security as your password. ### Best practices * Keep your API keys confidential * Don’t share your API keys in publicly accessible areas such as GitHub or client-side code * Regularly rotate your API keys to enhance security * If a key is compromised, revoke it immediately and generate a new one ### Revoking access If a key is compromised or no longer needed: 1. Navigate to the "API" tab in Workspace Settings 2. Locate the specific key 3. Click the ellipsis (three dots) icon and select 'delete' to immediately revoke access 4. Generate a new key if needed Deleting an API key only affects the integrations using that specific key. Other keys and integrations will continue to function normally. # Get a summary for a call get /v1/call-summaries/{callId} Retrieve an AI-generated summary of a specific call identified by its unique call ID. Call summaries are only available on OpenPhone Business plan. # Get a transcription for a call get /v1/call-transcripts/{id} Retrieve a detailed transcript of a specific call identified by its unique call ID. Call transcripts are only available on OpenPhone business plan. # Get recordings for a call get /v1/call-recordings/{callId} Retrieve a list of recordings associated with a specific call. The results are sorted chronologically, with the oldest recording segment appearing first in the list. # List calls get /v1/calls Fetch a paginated list of calls associated with a specific OpenPhone number and another number. # Changelog Stay up to date with the latest improvements to the API. ## 1.2.0 ### Minor Changes * Adds a property `externalId` to the contact model. Adds `externalId` and `source` as optional parameters to the Create Contact (`POST /contacts`) request. * Adds `externalId` and `source` as optional parameters to the Update Contact (`PATCH /contacts/:id`) request. * Added a route to list contacts (`GET /contacts`). ### Patch Changes * Fixed an issue where creating or updating a contact with an invalid custom field would result in 500 error. Sending an invalid custom field will now result in a 400 "Invalid Custom Field Item" error. ## 1.1.2 ### Patch Changes * Fixed an issue where paginated endpoints would return a string token for the next page at the end of paginated results. Now, they will correctly return the next page token as `null`. * Added a callout that the `totalItems` result field for the paginated endpoints is not functioning as expected and is not returning the true total items count. ## 1.1.1 ### Patch Changes * Fixes an issue where phone numbers in various routes were expected to be in E164 format, but the format was not being validated correctly. ## 1.1.0 ### Minor Changes * Adds a property, `restrictions`, to the objects in the response from list phone numbers (`GET /phone-numbers`). The new property contains information about regional restrictions for outbound calling and messaging from a phone number. ## 1.0.2 ### Patch Changes * Fixed an issue with list calls (`GET /calls`) where sending an empty participants param resulted in a 500 response. Sending an empty participants param will now result in a descriptive 400 response. * Fixes an issue where attempting to send a message to an international number would result in a 500 response if international messaging is not enabled in the workspace. With this fix, the 500 error response changed to a 403 with a descriptive message * Fixes a bug where the GET call recordings endpoint sometimes returned an empty array. * Fixes an issue that was preventing some call records from returning successfully from `GET /calls` * Fixes an issue where getting a contact by id would result in a 500 instead of a 404 when contact is not found. Now this will respond in a 404 with a descriptive message. * Fixes an issue where sending a message that contained only whitespace (`' '`, `'\n'`, etc.) resulted in a 500 error response. Now, this will respond with 400 and a validation error message instead. ## 1.0.1 ### Patch Changes * Fixes an issue with List Calls (`GET /calls`) where the user ID applied by default when the user ID parameter was not sent was being set to the workspace owner instead of the phone number owner. ## 1.0.0 ### Major Changes OpenPhone's Public API v1 release 🚀 Changes from the beta version include: * The `since` query parameter on "list calls" and "list messages" has been deprecated. It used to incorrectly behave as a `createdBefore`. Please use `createdAfter` instead, or `createdBefore` to maintain current functionality. * The `phoneNumberId` field for "send text message" has been deprecated. Please use `from` instead. * `/v0` endpoints have been deprecated. Please use `/v1` instead. # Get contact custom fields get /v1/contact-custom-fields Custom contact fields enhance your OpenPhone contacts with additional information beyond standard details like name, company, role, emails and phone numbers. These user-defined fields let you capture business-specific data. While you can only create or modify these fields in OpenPhone itself, this endpoint retrieves your existing custom properties. Use this information to accurately map and include important custom data when creating new contacts via the API. # Create a contact post /v1/contacts Create a contact for a workspace. # Delete a contact delete /v1/contacts/{id} Delete a contact by its unique identifier. # Get a contact by ID get /v1/contacts/{id} Retrieve detailed information about a specific contact in your OpenPhone workspace using the contact's unique identifier. # List contacts by externalIds and sources get /v1/contacts Fetch a paginated list of contacts associated with specific external IDs. Optionally narrow the results further by supplying a list of sources. While we do intend to offer a true "list all contacts" endpoint in the future, the `externalIds` parameter is currently **required** to narrow the result set to only the desired contacts, if they exist. # Update a contact by ID patch /v1/contacts/{id} Modify an existing contact in your OpenPhone workspace using the contact's unique identifier. # List Conversations get /v1/conversations Fetch a paginated list of conversations for a specific OpenPhone number. Results are returned in descending order based on the most recent conversation. # API response codes OpenPhone uses standard HTTP response codes to indicate request status. ## Response code categories * 2xx: Success * 4xx: Client-side errors * 5xx: Server-side errors Some 4xx errors include specific error codes for programmatic handling. ## Common response codes | Code | Status | Description | | ----- | ----------------- | ------------------------------------------------------------- | | `200` | OK | Request successful | | `201` | Created | Resource successfully created | | `202` | Accepted | Request accepted for processing | | `204` | No Content | Request successful, no content returned | | `400` | Bad Request | Invalid parameters | | `401` | Unauthorized | Missing or invalid API key | | `403` | Forbidden | Insufficient permissions or an account setting is not enabled | | `404` | Not Found | Resource doesn't exist | | `409` | Conflict | Conflict with another request | | `429` | Too Many Requests | Rate limit exceeded | | `500` | Server Error | OpenPhone-side issue | For 429 errors, implement exponential backoff in your requests. # Introduction Welcome to the OpenPhone API! ## Overview The OpenPhone API enables developers to integrate powerful communication features directly into their applications and workflows. Built on REST principles, our API provides a reliable and secure way to programmatically manage phone communications. ## Key features Industry-standard REST API design with JSON responses for easy integration API key-based authentication to ensure secure access to your account All API responses are returned in standardized JSON format Comprehensive documentation and [resources](/mdx/guides) to accelerate development ## Next steps Ready to dive deeper? Here are some helpful resources: * [Authentication guide](/mdx/api-reference/authentication) - Learn about securing your API requests * [Send your first message](/mdx/api-reference/send-your-first-message) - Quick start guide for messaging * [Partner directory](/mdx/api-reference/openphone-partner-directory) - Explore our list of development partners * [Build with AI LLMs](/mdx/guides/building-with-ai-llms) - Learn how to utilize this API alongside AI # Get a message by ID get /v1/messages/{id} Get a message by its unique identifier. # List messages get /v1/messages Retrieve a chronological list of messages exchanged between your OpenPhone number and specified participants, with support for filtering and pagination. # Send a text message post /v1/messages Send a text message from your OpenPhone number to a recipient. # OpenPhone partner directory Connect with experts to achieve your customer communications goals. Thinking about building with the OpenPhone API but don’t have the time or in-house expertise to get started? Our trusted OpenPhone Experts are here to help. Browse our [directory of partners](https://experts.openphone.com/) who offer tailored services to help you make the most of your OpenPhone setup. Whether it's integrating with other tools, optimizing your workflows, or getting onboarded smoothly, we've got you covered. Not sure where to start? [Tell us about your project](https://experts.openphone.com/wizard), and we'll connect you with the right partner.