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.
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.
|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.|
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.
|GET accounts/current||Acquisition of information on the authorized account.|
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.
|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.|
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.
|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.|
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.
|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.|
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.
|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.|
A transaction is the main characteristic of a purchase (date and amount) and is connected to a "customer".
|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.|
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
|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.|
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.
|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.|
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.
|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.|
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 firstname.lastname@example.org with the request to provide a secret key to use API for the Unqualified leads.
|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.|
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
|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 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
|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 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.
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.
|GET catalogs/list||Usedto retrievethe list of catalogs.|
|POST catalogs/set||Used to create/rename/delete catalogs.|
A catalog item is a piece of data stored in a catalog.
These methods can be used only by users having access to catalogs.
|GET catalog_elements/list||Used to retrievecatalog items.|
|POST catalog_elements/set||Used create/rename/delete catalog items.|
|GET links/list||Method used to get links.|
|POST links/set||Method used to link/unlink entities.|
A method presented below allows you to manage contacts, customers and transactions, as well as the connections between the main entities.
|POST elements/sync||A method for managing contacts, customers and lead, as well as the connections between them.|
The most common error codes can be found on this page.