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
Please visit our developers' website to learn more.
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.
Happy coding! 👩💻
Keys 🔑
Generating an API key
Note: Only admins of active accounts can create an API. If you're on a trial, reach out to 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 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
Frequently asked questions
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.
Do Beacon workflows run as a result of API actions?
Yes! Check out the FAQs in our workflows guide.
Are there rate limits for API calls?
Yes, 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.
If you exceed this limit, 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."}
Can I upload files via the API?
No, it's not currently possible to add files to File upload fields via the API.
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!