Permissions and Abilities

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.

How a request is allowed

A key belongs to one team member in one account. Alaaqat allows a request only when both of these hold:

  1. The key carries the ability the endpoint needs. The abilities are listed on the key's card in Settings > Integrations > API.
  2. The team member who created the key has the permission for the action in that account, the same permission the action needs in the app.

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.

When a request is refused

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 404 on 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 answer 404 whatever abilities the key carries. Only the endpoints on this page accept API keys.

CRM objects

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.

Records

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-selected
POST {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.

Properties and property groups

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.

Notes

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

Canned responses

Ability Endpoints Team member permission
predefined-response-index GET /api/conversations/predefined-responses
GET /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

WhatsApp

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.

Current user

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.

Abilities that are easy to miss

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.

All abilities

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