Note: API access is available on our Standard, Premium, and Ultimate plans
An API allows you to integrate your applications/software with Beacon. You can use our open REST API to communicate with your Beacon account to get, add or even delete data.
For instance, whenever someone logs into your website, you could automatically create a Person record in Beacon. The world is your oyster or APIster!
Beacon's API is currently free to use for active customers, but there is a (generous) rate limit.
API documentation
Our main API documentation, with details of record structures, field keys, and making API calls, are available our developers' website.
Note: Our API documentation is automatically generated based on how your database is configured. You'll need to log in to view the API docs.
We also have additional documentation for other elements of our API:
Happy coding! 👩💻
Tip: When using Read, List, or Filter endpoints, we will return data from those records AND from any records they link to via point to another record fields. Use the ?populate=true or ?populate=false parameter on your URL to control whether you’d like to include this extra data from linked records.
Keys 🔑
Generating an API key
Note: Only admins of active accounts can create an API. If you're on a trial, simply reach out to your salesperson, or our support team using the chat button or email [email protected].
API keys can be created directly from your Beacon account. To create a new API key:
Log in to Beacon
Head to Settings > API keys
Click 'Create API key'
A popup will show up with your new key. After you click the Copy button, the popup will disappear, and you will never be able to see it again (for many good security reasons).
Warning: You should treat API keys the same as a password for your Beacon account. If you share them with others, please use a password-sharing app, don't store them directly in any code (we recommend using Environmental Stores or Keys), and if you do accidentally share them publicly you should revoke them and create a new key.
Revoking API keys
Instead of deleting, we allow you to revoke an API key. This means that you can stop an API key from working (which you might want to do due to accidentally sharing it publicly). To revoke a key, head to Settings > API keys. You'll see the 'Revoke' button next to the last four digits of each key.
Once revoked, you'll see the 'Revoked at' column has been filled out, and any API calls using that key will get an error back with the following 403 response:
{
"error": {
"code": "invalid_api_key",
"message": "Your API key is invalid."
}
}Note: Once you revoke an API key, you can not un-revoke it; it is revoked forever
Rate limits
We rate limit our API to better protect our systems from abuse.
You are limited to making up to 300 requests per minute. This is a pretty high limit, so this shouldn't restrict your normal use of the Beacon API.
For bulk API requests (e.g. bulk upsert), this limit is 60 requests per minute.
If you exceed these limits, you will be returned a 429 HTTP status code and the following in the response body:
{"error": {"code": "rate_limit_exceeded","message": "You have exceeded
the rate limit for API calls. Please try again in a few minutes."}
Frequently asked questions
Do Beacon workflows run as a result of API actions?
Yes! Check out the FAQs in our workflows guide.
Can I download files from fields via the API?
Yes, reading any record that contains files in a File upload field will return a signed URL for each attachment. The signed URL will expire 60 minutes after it is generated.
Can I upload files to fields via the API?
Yes, you can upload files to a signed URL and then pass that URL to a file upload field in Beacon. See our full guidance here.
Can I access relationships via the API?
No, the relationships feature is not currently accessible via the API. If you're actually looking to link records together (aka point to another record fields in Beacon) that is absolutely possible via the API, yes!
Can I get a list of record types via the API?
Yes, you can use this endpoint to list record types (aka 'entity types' or 'table definitions'):
GET https://api.beaconcrm.org/v1/account/{account_id}/entity_types
Can I run exports with the API?
Yes, you can trigger exports to be run using existing templates.
Recently run exports are also available to be retrieved, and documented in the developer docs.
How are filters structured via the API?
We've got an extensive guide to filter structures, operators, and values available on our page here.
What validation does each field type have?
We've documented the valid values that can be passed to each field type in a guide here.
Can I filter for deleted records with the API?
Yes, you can use the ?archived=true parameter to filter for deleted records.