Levitate Public API
The Levitate Public API lets you read and write your Levitate data programmatically — managing contacts and companies, creating notes, and more — directly from your own scripts, applications, or automation tools.
Note: The Public API feature must be enabled on your account before you can generate a key or make requests. Contact your Success Specialist or Support to have it enabled.
What You Can Do
The Public API is organized around the following resources:
| Resource | What it covers |
|---|---|
| Contacts | Retrieve a single contact, list contacts, create and update contacts, and run a filtered search. |
| Key Facts | Read, add, update, and remove the key facts stored on a contact — birthdays, anniversaries, hobbies, and other personal details Levitate uses for timely, personalized outreach. |
| Companies | Retrieve, list, create, update, and delete company records. |
| Notes | Retrieve, list, create, and delete notes attached to contacts or companies. |
For the full list of endpoints, parameters, and response schemas, see the API Reference below.
Note: The Public API is a set of endpoints your own code calls. It is not an integration and it does not sync on its own. Enabling the feature and generating a key does not move any data by itself, and the API never connects out to a CRM, AMS, or other source system to retrieve records. Moving contacts in from another system means writing code that reads from that system and creates or updates them in Levitate. If you want data to flow automatically from another platform without building it yourself, ask your Success Specialist whether a direct integration is available.
What Contact Data Is Available
A contact returned by the API is the full profile rather than just name and contact details. Alongside names, email addresses, phone numbers, and mailing address, it includes tags, custom fields, and key facts — so your app or script can read and drive the same categorization your team works with in the app.
Most profile fields can be written as well as read. A handful are maintained by Levitate and are read-only, including the contact's source, its associated company and owner, email and text subscription status, and last communication date. Key facts are read-only on the profile itself and are managed through their own endpoints on the contact; a key fact supplied by an official Levitate integration can't be modified through the API at all.
The API Reference lists every field, which of them are writable, and the exact response shape.
Authentication
All Public API endpoints live under the base URL https://api.levitate.ai and are prefixed with /public/v1. Every request must include a credential as a Bearer token in the Authorization header:
Authorization: Bearer YOUR_TOKEN
There are two kinds of credentials, depending on who is making the request.
Personal API Key
A Personal API Key is the simplest option and the right choice when you are writing a script or connecting a tool that acts as you. The key is tied to your individual Levitate user, and any user on the account can generate one regardless of admin status.
See the API Keys article for step-by-step instructions on generating and copying your Personal API Key.
Keep your key secret — anyone who has it can make API requests on your behalf. If a key is compromised, generate a new one and delete the old one.
OAuth Bearer Token
If you are building an application that acts on behalf of other Levitate users, use an OAuth client instead of a personal key. Your application sends the user through the OAuth authorization code flow with PKCE, the user approves access, and your application receives a bearer token to send in the same Authorization header.
See the OAuth Clients for the Public API article for how to create and manage OAuth clients.
Note: API keys scoped to the Levitate MCP Server cannot be used against the Public API. Generate a Personal API Key or use an OAuth client instead.
Scopes
Access is controlled by scopes. You choose scopes when you create an OAuth client, and also when you generate a Personal API Key — at least one scope is required in both cases.
A scope is a permission boundary: it defines what a credential is allowed to reach if something calls the API with it. It is not a data selection, and it does not import or sync anything. Granting levitate:contacts does not bring contacts into Levitate or send them anywhere — it only means that code holding that credential is permitted to read and write those records.
| Scope | Access Granted |
|---|---|
levitate:contacts |
Read and write contacts, companies, notes, and key facts |
Despite its name, levitate:contacts covers contact-related resources — companies, notes, and key facts — not just contacts. Currently this includes every endpoint in the /public/v1 API, but as new functionality is added, it may require additional scopes.
Request only the scopes your integration actually needs. Broader access increases the impact if a credential is ever exposed.
Scopes and user permissions
A scope and a user permission are two separate checks, and every request has to pass both. The scope controls what the key or application is allowed to reach. The acting user's own Levitate permissions still apply on top of that, so a credential can never read or change more than that user can in the app. Granting levitate:contacts to a key does not widen the underlying user's access.
Common Use Cases
These are the patterns customers most often build against the Public API.
Create or update contacts from another system
The most common use. Your code reads records from wherever they live — a CRM, a spreadsheet export, a web form, an internal database — and writes them to Levitate with POST /public/v1/contacts to create or PATCH /public/v1/contacts/{id} to update. Tags and custom fields can be set in the same request, so a contact can arrive already categorized instead of needing a second pass.
Keep tags and custom fields current
Because tags and custom fields are writable, an outside system can drive segmentation inside Levitate. A policy renewal, a donation, a membership tier change, or a lifecycle stage in another tool can each be reflected as a tag or custom field value, which then makes the contact reachable by the automations and email audiences built on top of it. Tag names that don't exist yet are created automatically when you write them.
Log activity from another tool as a note
Notes attach to contacts or companies, so activity that happens outside Levitate can still land on the record your team actually reads. A single note can reference up to 25 contacts or companies, and can either be shared with the whole account or kept private.
Pull a filtered list of contacts
POST /public/v1/contacts/search accepts a boolean filter tree, so conditions can be combined with AND, OR, and NOT instead of filtering on your end. You can filter on tags and custom fields, company, location, source, visibility, subscription status, and dates such as when a contact was created or last communicated with. The API Reference documents the full field and operator vocabulary.
Best Practices
A few behaviors are worth knowing before you build.
Note: On an update, an array you supply replaces what was there rather than merging into it. Sending tags in a PATCH overwrites the contact's entire tag list, so adding a single tag means reading the current tags, appending to them, and sending the full list back. The same applies to email addresses, phone numbers, and custom fields.
- Page through large result sets. List and search endpoints return 25 records per page by default and 100 at most, so anything larger has to be paged.
- Generate a separate key per integration so you can revoke one without disrupting the others.
- Request the narrowest scope that covers what you are building.
- Plan for key expiration. Personal API Keys expire and can't be renewed, so a long-running integration needs a replacement key in place before the old one lapses.
- Try endpoints in the browser first using the authorization panel in the API Reference before writing any code.
API Reference
Complete, always-current reference documentation — every endpoint, its parameters, and example requests and responses — is published at api.levitate.ai/docs.
The reference is interactive. It includes a built-in authorization panel that walks you through the OAuth flow in the browser, so you can generate a token and send real requests against your own account to try an endpoint before writing any code.
FAQs
Q: Who can use the Public API?
A: Any Levitate user with a Personal API Key can make requests. The Public API feature must be enabled on your account first — contact your Success Specialist or Support to request access.
Q: Will setting up an API key pull my contacts in from my other system?
A: No. An API key is a credential, not a connection — it doesn't move data on its own, and the Public API never reaches into your CRM, AMS, or other systems to retrieve records. Bringing contacts in means writing code that reads from that system and creates or updates them in Levitate. If you'd rather have data flow in automatically, ask your Success Specialist whether a direct integration covers your system.
Q: Does the API include tags and key facts, or only basic contact details?
A: Tags, custom fields, and key facts are all included. Tags and custom fields can be read and written directly on the contact, and key facts are managed through their own endpoints. See What Contact Data Is Available.
Q: Do my API keys expire?
A: Personal API Keys do — you choose 30, 90, 180, or 365 days when you create one, and they can't be renewed or extended. Generate a replacement before the old key lapses, point your integration at it, and delete the old one. See the API Keys article.
Q: Where do I get my API Key?
A: See the API Keys article for step-by-step instructions on generating and copying your Personal API Key.
Q: Should I use a Personal API Key or an OAuth client?
A: Use a Personal API Key when the integration acts as you — a script, a scheduled job, or a tool wired up to your own data. Use an OAuth client when you are building an application that other Levitate users will authorize against their own accounts.
Q: Can I use one API Key for multiple integrations?
A: Yes, but best practice is to generate a separate key for each integration so you can revoke one without disrupting the others.
Q: What happens if my API Key is exposed?
A: Delete the compromised key immediately and generate a new one. Deleting a key takes effect right away — any request still using the old key will fail with an authorization error.
Q: Can I use my Zapier API key with the Public API?
A: No. Zapier keys are account-level keys used only for the Zapier connection. To call the Public API, generate a Personal API Key.