Main objects and methods

For a developer, amoCRM system is a relational database. The system contains main and auxiliary entities (in substance, data tables) that may be linked between each other. Access to them is provided through API.

Authorization

In order to access system data through both interfaces and API, user account authorization is required. All operations through API also take place with regard to access privileges of the user authorized in the account. All methods may be used only after authorization.

API METHOD DESCRIPTION
POST /private/api/auth.php In case of successful authorization, this method returns the user’s session ID, which must be used while accessing to other API methods.

Account

Though API, you can obtain all necessary information about the account: name, paid period, account’s users and their privileges, guides on custom contact and lead fields, lead status guide, event types guide, task types guide and other account parameters.

API METHOD DESCRIPTION
GET accounts/current Acquisition of information on the authorized account.

Contact

This is one of the general entities of the system. It consists of a predefined set of fields and custom fields created by the account administrator. Each contact may take part in one or more leads, or may be not linked to any leads at all. Each contact can be linked with a single company.

The contact’s e-mail address and phone number are used as unique identifiers in association with other systems. For example, information about calls made, about e-mail communications falls exactly within the contact’s events.

A responsible user may be assigned to each contact in order to assign access privileges among the account’s personnel.

API METHOD DESCRIPTION
POST contacts/set This method allows to add contacts one by one or in packages, and also to update data for the already existing contacts.
GET contacts/list A method for obtaining contact lists with possibility of filtration and page-by-page selection.
GET contacts/links A method for obtaining a list of links between leads and contacts.

Lead

This is one of the general entities of the system. It consists of a predefined set of fields and custom fields created by the account administrator. Each lead can be linked to one or more contacts, or to none.

A responsible user may be assigned to each lead in order to assign access privileges among the account’s personnel.

Each lead has a status, which specifies the current position of the lead within its lifecycle (business process). Status must be necessarily assigned to any lead. The list of statuses within the account may be changed except for two final system statuses.

API METHOD DESCRIPTION
POST leads/set This method allows to create new leads, and also to update information on the already existing leads.
GET leads/list This method allows obtaining detailed information on already created leads with possibility of filtration and page-by-page selection.
GET contacts/links A method for obtaining a list of links between leads and contacts.

Company

This entity is identical with “contact” entity. It consists of a predefined set of fields and custom fields created by the account administrator. Each company may take part in one or more leads, or may be not linked to any leads at all.

The e-mail address and phone number are used as identifiers in association with other systems.

A responsible user may be assigned to each company in order to assign access privileges among the account’s personnel.

API METHOD DESCRIPTION
POST company/set This method allows to add companies one by one or in packages, and also to update data for the already existing companies.
GET company/list A method for obtaining company lists with possibility of filtration and page-by-page selection.

Customerv3

A customer is similar to a lead. It consists of a set of preset fields, and account administrators can add additional custom fields. Each customer may be attached to one or more contacts or not attached at all.

For every customer, user access rights can be modified including assigning a user as the responsible manager.

The current stage that a customer is in is also displayed. Stages represent the position of the customer in the purchase process.

API METHOD DESCRIPTION
POST customers/set A method that allows you to create / update / delete a customer individually or in batches.
GET customers/list This method allows obtaining detailed information on already created customers with possibility of filtration and page-by-page selection.

Transactionv3

A transaction is the main characteristic of a purchase (date and amount) and is connected to a "customer".

API METHOD DESCRIPTION
POST transactions/set A method for creating/deleting transactions individually or in batches.
GET transactions/list A method for getting a filterable list of transactions.

Task

Each task must necessarily have a responsible user and date (day and time) assigned to it. Also, a task may be linked to a lead or contact, but not necessarily. It may be not linked to any object.

It is possible to set a result for a completed task by means of POST notes/set method

API METHOD DESCRIPTION
POST tasks/set This method allows to create new tasks, and also to update information on the already existing tasks.
GET tasks/list A method for obtaining a list of already created tasks with possibility of filtration and page-by-page selection.

Event (note)

Events provide possibility of adding additional structured or unstructured information to a contact or a lead. Events may be of two types: system events (calls, SMS-messages, etc.) or user created events (notes, files). Events are displayed in cards along with tasks, since they are not linked to a responsible user or date.

Commonly, events are used by widgets for adding additional information to a lead or a contact, when it is inconvenient to use custom fields. Events can be easily used as a log, since they are always displayed in chronological order within the stream, and if your information is linked to a date (chronology), it is advisable to use events here.

API METHOD DESCRIPTION
POST notes/set This method allows to add events one by one or in packages , and also to update information on the already existing events.
GET notes/list A method for obtaining a list of events with possibility of filtration and page-by-page selection.

Custom fields

This method allows creating or deleting custom fields one by one or in packages. The user will not be able to change their values from the interface, but can browse them and use them for filtering.

Creation or deletion of a field is also possible from the interface.

API METHOD DESCRIPTION
POST fields/set This method allows to add fields one by one or in packages, and also to delete them.
Managing custom fields This section describes how to transmit values of custom fields.

Unqualified leads

This is a new system entity. All the requests originated from different types of integrations: email, telephony and web forms, and which haven't yet been sorted by the user (meaning that no lead or contact hasn't been created yet for those requests). User of the account can accept an unqualified lead - in this case a new lead will be created, as well as contact and company, if there is corresponding info in the request. Unqualified lead can also be declined.

For now API for this entity is running the test mode and to gain access to it you'll need to send an email to support@amocrm.com with the request to provide a secret key to use API for the Unqualified leads.

API Method Description
GET unsorted/list Method used to receive the list of Unqualified leads with filter and page selection options.
GET unsorted/get_all_summary Method used to receive aggregated information on the accepted and declined leads.
POST unsorted/accept Method used to accept leads one by one or in bulk.
POST unsorted/decline Method used to decline leads one by one or in bulk.
POST unsorted/add Method used to add unqualified leads one by one or in bulk.

WebHooks

Each amoCRM account has ability to communicate with a web-server. These WebHooks can be used for updating information about leads in your web-store, sending SMS-notifications, or automation of lead conducting process. Each WebHook can be adjusted for certain operations and events. The account’s administrator can adjust hooks at “Settings”->“API” page.
The description of WebHook mechanism can be found here.

Methods to work with account WebHooks settings
These methods can be used only by the administrator of the account

API Method Description
GET webhooks/list Method used to get the list of WebHooks.
POST webhooks/subscribe Method allows to add addresses to send WebHooks one by one or in bulk.
POST webhooks/unsubscribe Method allows to delete addresses for sending WebHooks one by one or in bulk.

Lead Statuses

Lead Statuses are a sequence of stages in the pipeline that a potential client (lead) undergoes before the conversion. amoCRM allows for creating a number of pipelines in one account with different set of statuses for each pipeline to monitor movement of the lead in each pipeline. In total up to 10 pipelines can be created in one amoCRM account. Each pipeline can have up to 100 statuses (including Won and Lost statuses).
Administrator of the account can configure the statuses on the page Settings -> Pipeline Settings.

Methods to work with pipeline settings in the account
These methods are available only to the administrator of the account

API Method DESCRIPTION
GET pipelines/list Method used to receive the list of lead statuses grouped by a pipeline
POST pipelines/set Method to add or edit pipelines and lead statuses one by one or in bulk.
POST pipelines/delete Method to delete pipelines one by one or in bulk.

Digital pipeline

Digital pipeline allows you to set various actions and automatically change the lead status when certain events occur.
Administrator of the account can configure the digital pipeline on the leads page by clicking "More" -> Digital Pipeline.
For details on digital pipeline settings please go to this page.

Catalogsv3

A catalog is a datastore. You can attach catalog items to lead cards. These methods can be used only by users who have access to catalogs.

API Method DESCRIPTION
GET catalogs/list Usedto retrievethe list of catalogs.
POST catalogs/set Used to create/rename/delete catalogs.

Catalog elementsv3

A catalog item is a piece of data stored in a catalog.

These methods can be used only by users having access to catalogs.

API Method DESCRIPTION
GET catalog_elements/list Used to retrievecatalog items.
POST catalog_elements/set Used create/rename/delete catalog items.

Linksv3

This methods allows you to manage links between catalog elements and other entities.

API Method DESCRIPTION
GET links/list Method used to get links.
POST links/set Method used to link/unlink entities.

Elementsv3

A method presented below allows you to manage contacts, customers and transactions, as well as the connections between the main entities.

API Method DESCRIPTION
POST elements/sync A method for managing contacts, customers and lead, as well as the connections between them.

Error codes

The most common error codes can be found on this page.