An API key carries a list of abilities, chosen when the key is created. Each endpoint of the public API needs one ability, and a key can call only the endpoints its abilities cover. Giving a key only the abilities an integration needs limits the damage if the key ever leaks: a key that can only read contacts can't delete deals.
This page lists every ability and the endpoints it opens. To create a key and choose its abilities, see Authentication.
A key belongs to one team member in one account. Alaaqat allows a request only when both of these hold:
An ability never grants a permission. If the team member can't delete contacts in the app, a key with
contact-delete can't delete them either.
Permissions also decide which records a request sees. A list endpoint returns the records the team member can see in the app: all of them with View All Contacts, or only their team's or their own with View Team Contacts or View User's Contacts. The same applies to every object.
| Status | Meaning |
|---|---|
| 401 | The key is missing, wrong, expired or revoked. |
| 403 | The key doesn't carry the ability the endpoint needs, or the team member lacks the permission for the action. The message tells the two apart. |
| 404 | The endpoint isn't open to API keys at all, or the record doesn't exist in the account. |
| 423 | The team member who created the key is disabled in the account, or the account is scheduled for deletion. |
{info} A
404on an endpoint you can see the app use is expected. Many requests the app makes for itself, such as those behind the inbox, workflows and webhook settings, aren't part of the public API. With an API key, they answer404whatever abilities the key carries. Only the endpoints on this page accept API keys.
Contacts, companies, deals, tickets, products and invoices share the same set of abilities. Each ability starts with the object's name:
| Object | Ability prefix | Endpoint path |
|---|---|---|
| Contacts | contact |
/api/contacts |
| Companies | company |
/api/companies |
| Deals | deal |
/api/deals |
| Tickets | ticket |
/api/tickets |
| Products | product |
/api/products |
| Invoices | invoice |
/api/invoices |
In the tables below, {object} stands for the prefix and {path} for the endpoint path. All paths start with
https://app.alaaqat.com. The permission column gives the contact permission. For the other objects, the
team member needs the matching permission of that object, such as Edit Deal for deals.
| Ability | Endpoints | Team member permission |
|---|---|---|
{object}-index |
GET {path} (list)POST {path}/check-duplicates |
List: View All Contacts, View Team Contacts or View User's Contacts Check duplicates: View All Contacts |
{object}-show |
GET {path}/{id} |
View Contact Details, View Team Contacts or View User's Contacts |
{object}-create |
POST {path} |
Create New Contact |
{object}-update |
PUT {path}/{id}PUT {path}/update-selectedPOST {path}/{id}/attach-…POST {path}/{id}/detach-… |
Edit Contact |
{object}-delete |
DELETE {path}/delete-selected |
Delete Contact |
Attaching links a record to records of another object, for example POST /api/contacts/{id}/attach-deals, and
detaching removes one link, for example POST /api/contacts/{id}/detach-deal. Every object can be linked to
every other one.
| Ability | Endpoints | Team member permission |
|---|---|---|
{object}-property-index |
GET {path}/properties |
None |
{object}-property-create |
POST {path}/properties |
Create Custom Field |
{object}-property-update |
PUT {path}/properties/{id} |
Edit Custom Field |
{object}-property-delete |
DELETE {path}/properties/{id} |
Delete Custom Field |
{object}-property-favorite |
PUT {path}/properties/{id}/favorite |
Favorite Custom Field |
{object}-property-group-index |
GET {path}/properties/groups |
View Field Groups |
{object}-property-group-create |
POST {path}/properties/groups |
Create Field Group |
{object}-property-group-update |
PUT {path}/properties/groups/{id} |
Edit Field Group |
{object}-property-group-delete |
DELETE {path}/properties/groups/{id} |
Delete Field Group |
The property and field group permissions are the same for every object.
| Ability | Endpoints | Team member permission |
|---|---|---|
{object}-note-index |
GET {path}/{id}/notes |
View All Notes on Contact |
{object}-note-create |
POST {path}/{id}/notes |
Add Note to Contact |
{object}-note-update |
PUT {path}/{id}/notes/{note_id} |
Edit Note on Contact |
{object}-note-delete |
DELETE {path}/{id}/notes/{note_id} |
Delete Note from Contact |
| Ability | Endpoints | Team member permission |
|---|---|---|
predefined-response-index |
GET /api/conversations/predefined-responsesGET /api/conversations/predefined-responses/{id} |
View Canned Responses |
predefined-response-create |
POST /api/conversations/predefined-responses |
Create New Canned Response |
predefined-response-update |
PUT /api/conversations/predefined-responses/{id} |
Edit Canned Response |
predefined-response-delete |
DELETE /api/conversations/predefined-responses/{id} |
Delete Canned Response |
| Ability | Endpoints | Team member permission |
|---|---|---|
broadcast-send |
POST /api/broadcasts/{id}/send (Send Template) |
Send Messages |
broadcast-send-otp |
POST /api/broadcasts/{id}/send-otp (Send OTP)POST /api/verifications/{id}/verify (Verify OTP) |
Send Messages |
A key whose only abilities are broadcast-send-otp and current-user is a verification-code key, which every
plan can create. See Authentication.
| Ability | Endpoints | Team member permission |
|---|---|---|
current-user |
GET /api/me (Current user) |
None |
Add current-user to any key: it lets an integration check that its key works and see which team member it
acts as.
| To… | The key needs | Not |
|---|---|---|
| Attach or detach records, for example contacts to a deal | {object}-update of the record in the URL |
A separate attach ability |
Update several records at once (update-selected) |
{object}-update |
A bulk ability |
| Check for duplicates | {object}-index |
{object}-show |
| Read a single canned response | predefined-response-index |
A show ability |
| Verify a code | broadcast-send-otp |
A verify ability |
For attach and detach, the ability belongs to the object in the URL. Attaching contacts to a deal through
/api/deals/{id}/attach-contacts needs deal-update; doing it through
/api/contacts/{id}/attach-deals needs contact-update.
Contacts: contact-index, contact-show, contact-create, contact-update, contact-delete,
contact-property-index, contact-property-create, contact-property-update, contact-property-delete,
contact-property-favorite, contact-property-group-index, contact-property-group-create,
contact-property-group-update, contact-property-group-delete, contact-note-index, contact-note-create,
contact-note-update, contact-note-delete
Companies: company-index, company-show, company-create, company-update, company-delete,
company-property-index, company-property-create, company-property-update, company-property-delete,
company-property-favorite, company-property-group-index, company-property-group-create,
company-property-group-update, company-property-group-delete, company-note-index, company-note-create,
company-note-update, company-note-delete
Deals: deal-index, deal-show, deal-create, deal-update, deal-delete, deal-property-index,
deal-property-create, deal-property-update, deal-property-delete, deal-property-favorite,
deal-property-group-index, deal-property-group-create, deal-property-group-update,
deal-property-group-delete, deal-note-index, deal-note-create, deal-note-update, deal-note-delete
Tickets: ticket-index, ticket-show, ticket-create, ticket-update, ticket-delete,
ticket-property-index, ticket-property-create, ticket-property-update, ticket-property-delete,
ticket-property-favorite, ticket-property-group-index, ticket-property-group-create,
ticket-property-group-update, ticket-property-group-delete, ticket-note-index, ticket-note-create,
ticket-note-update, ticket-note-delete
Products: product-index, product-show, product-create, product-update, product-delete,
product-property-index, product-property-create, product-property-update, product-property-delete,
product-property-favorite, product-property-group-index, product-property-group-create,
product-property-group-update, product-property-group-delete, product-note-index, product-note-create,
product-note-update, product-note-delete
Invoices: invoice-index, invoice-show, invoice-create, invoice-update, invoice-delete,
invoice-property-index, invoice-property-create, invoice-property-update, invoice-property-delete,
invoice-property-favorite, invoice-property-group-index, invoice-property-group-create,
invoice-property-group-update, invoice-property-group-delete, invoice-note-index, invoice-note-create,
invoice-note-update, invoice-note-delete
Canned responses: predefined-response-index, predefined-response-create, predefined-response-update,
predefined-response-delete
WhatsApp: broadcast-send, broadcast-send-otp
Current user: current-user