To-dos

The task must necessarily have a responsible and a date (number and time). Also, a task can be associated with a lead or contact, but not necessarily, it may not be associated with any object. The main essence of the system are to-dos. You can set the result for a closed task using the notes method.


Adding and updating a task

This method allows you to add a new one or modify an existing task. To set the result by task, use the notes method, setting the appropriate note type.

Method URL

POST/api/v2/tasks

Options
Parameter Type Description
add array List of added to-dos
update array Modify existing to-dos. All the parameters that are described in add also work in the update
add/element_id int Unique identifier of a contact or lead (lead or contact is specified in element_type)
add/element_type int The type of the element to be attached (1-contact, 2-lead, 3-company, 12-customer)
add/complete_till_at timestamp The date to which you want to complete the task. If the time is 23:59, then "All day" will be displayed in the system interfaces instead of time.
add/task_type int Type of task (task types see here)
add/text string Task text
add/created_at timestamp Date of creation of this task (optional parameter)
add/updated_at timestamp Last changed date for this task (optional)
add/responsible_user_id int Unique identifier of the responsible user
add/is_completed bool Task completed or not
add/created_by int Unique identifier of the creator of the task
update/id
require
int The unique identifier of the task being updated
update/updated_at
require
timestamp The date of the last modification of this entity, if the parameter is not specified, or it is less than that available in the database, the update will not occur
update/text
require
string Task text
Types of tasks
Code Description
1 Call
2 Meeting
3 Write an email
Response parameters
Parameter Description
id The unique identifier of the new entity
request_id The unique identifier of the entity in the client program, if request_id is not passed in the request, it is automatically generated
_links Array containing information about the request
_links/self An array containing information about the current request
_links/self/href Relative URL of the current request
_links/self/method The method of the current request
_embedded An array containing information adjacent to the query
_embedded/items An array containing information for each individual element

Response Headers contains the following headers:

  • Content-Type:application/hal+json

  • Runtime-Timestamp: 1508320306

Example query
  1. {
  2.    add: [
  3.       {
  4.          element_id: "496537",
  5.          element_type: "1",
  6.          complete_till_at: "1508706000",
  7.          task_type: "1",
  8.          text: "Do not forget to call back",
  9.          created_at: "1508706000",
  10.          updated_at: "1508706000",
  11.          responsible_user_id: "504141",
  12.          created_by: "504141"
  13.       }
  14.    ]
  15. }
Example response
  1. {
  2.    _links: {
  3.       self: {
  4.          href: "/api/v2/tasks",
  5.          method: "post"
  6.       }
  7.    },
  8.    _embedded: {
  9.       items: [
  10.          {
  11.             id: 930790,
  12.             _links: {
  13.                self: {
  14.                   href: "/api/v2/tasks?id=930790",
  15.                   method: "get"
  16.                }
  17.             }
  18.          }
  19.       ]
  20.    }
  21. }

An example of integration that works with tasks

To add a task, you need to describe an array containing information about the task and put it into an array of the following form:

Example integration
  1. $tasks['add']=array(
  2.   #Bind to the lead
  3.  array(
  4.     'element_id'=>3698754, #ID of the lead
  5.    'element_type'=>2, #Show that this is a lead, not a contact
  6.    'task_type'=>1, #Call
  7.    'text'=>'My First Task',
  8.     'responsible_user_id'=>109999,
  9.     'complete_till_at'=>1375285346
  10.   ),
  11.   #Bind to the lead
  12.  array(
  13.     'element_id'=>3698752,
  14.     'element_type'=>2,
  15.     'task_type'=>3, #Email
  16.    'text'=>'My Second Task',
  17.     'responsible_user_id'=>109999,
  18.     'complete_till_at'=>1375198975
  19.   ),
  20.   #Bind to contact
  21.  array(
  22.     'element_id'=>10773004,
  23.     'element_type'=>1,
  24.     'task_type'=>2, #Meeting
  25.    'text'=>'My Third Task',
  26.     'responsible_user_id'=>109999,
  27.     'complete_till_at'=>1375285442
  28.   )
  29. );
  30. /* Now prepare the data needed to query the server */
  31. $subdomain='test'; #Our account - subdomain
  32. #Generate a link for the request
  33. $link='https://'.$subdomain.'.amocrm.com/api/v2/tasks';
  34. /* We need to initiate a request to the server. We use the cURL library (supplied as part of PHP). More about
  35. work with this
  36. library you can read in the manual. */
  37. $curl=curl_init(); #Save the cURL session descriptor
  38. #Set the necessary options for the cURL session
  39. curl_setopt($curl,CURLOPT_RETURNTRANSFER,true);
  40. curl_setopt($curl,CURLOPT_USERAGENT,'amoCRM-API-client/1.0');
  41. curl_setopt($curl,CURLOPT_URL,$link);
  42. curl_setopt($curl,CURLOPT_CUSTOMREQUEST,'POST');
  43. curl_setopt($curl,CURLOPT_POSTFIELDS,json_encode($tasks));
  44. curl_setopt($curl,CURLOPT_HTTPHEADER,array('Content-Type: application/json'));
  45. curl_setopt($curl,CURLOPT_HEADER,false);
  46. curl_setopt($curl,CURLOPT_COOKIEFILE,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
  47. curl_setopt($curl,CURLOPT_COOKIEJAR,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
  48. curl_setopt($curl,CURLOPT_SSL_VERIFYPEER,0);
  49. curl_setopt($curl,CURLOPT_SSL_VERIFYHOST,0);
  50. $out=curl_exec($curl); #Initiate a request to the API and save the response to a variable
  51. $code=curl_getinfo($curl,CURLINFO_HTTP_CODE);
  52. /* Now we can process the response received from the server. This is an example. You can process the data in your own way. */
  53. $code=(int)$code;
  54. $errors=array(
  55.   301=>'Moved permanently',
  56.   400=>'Bad request',
  57.   401=>'Unauthorized',
  58.   403=>'Forbidden',
  59.   404=>'Not found',
  60.   500=>'Internal server error',
  61.   502=>'Bad gateway',
  62.   503=>'Service unavailable'
  63. );
  64. try
  65. {
  66.   #If the response code is not 200 or 204, we return an error message
  67.  if($code!=200 && $code!=204)
  68.     throw new Exception(isset($errors[$code]) ? $errors[$code] : 'Undescribed error',$code);
  69. }
  70. catch(Exception $E)
  71. {
  72.   die('Error: '.$E->getMessage().PHP_EOL.'Error code: '.$E->getCode());
  73. }

Task list

Method for obtaining a list of tasks with the possibility of filtering and paging. Restriction on data returned on one page (offset) - 500 tasks. Overdue tasks - those tasks where complete_till_at is less than the current time and status - is not closed.

Method URL

GET/api/v2/tasks

GET options
Parameter Description
id Select element with given id
limit_rows Number of selectable rows (system limit 500)
limit_offset Selection reference (from which row to choose). Works only if limit_rows is also specified
element_id An additional search filter, according to the id elements of the entity
responsible_user_id Additional search filter, by responsible user
type Obtaining data by the type of the specified entity (lead / contact / company / customer)
Response parameters
Parameter Type Description
id int The unique identifier of the task
element_id int Unique identifier of a contact or lead (lead or contact is specified in element_type)
element_type int The type of the element to be attached (1-contact, 2-lead, 3-company, 12-customer)
complete_till_at timestamp The date to which you want to complete the task. If the time is 23:59, then "All day" will be displayed in the system interfaces instead of time.
task_type int Task type (see task types)
text string Task text
created_at timestamp Date of creation of this task (optional parameter)
updated_at timestamp Last changed date for this task (optional)
responsible_user_id int Unique identifier of the responsible user
is_completed bool Task completed or not
created_by int The unique identifier of the creator of the task
account_id int Unique account ID
group_id int id of the group in which the user is associated with the task
result array
_links array Array containing information about the request
_links/self array An array containing information about the current request
_links/self/href string Relative URL of the current request
_links/self/method string Method of the current request
_embedded array An array containing information adjacent to the query
_embedded/items array An array containing information for each individual element
Example query

https://example.amocrm.com/api/v2/task

Example response
  1. {
  2.    _links: {
  3.       self: {
  4.          href: "/api/v2/tasks",
  5.          method: "get"
  6.       }
  7.    },
  8.    _embedded: {
  9.       items: [
  10.          {
  11.             id: 930789,
  12.             responsible_user_id: 504141,
  13.             created_by: 504141,
  14.             created_at: 1508619600,
  15.             updated_at: 1508619600,
  16.             account_id: 13667499,
  17.             group_id: 0,
  18.             element_type: 3,
  19.             element_id: 1099180,
  20.             is_completed: false,
  21.             task_type: 1,
  22.             complete_till_at: 1508878800,
  23.             text: "Do not forget to call",
  24.             result: [],
  25.             _links: {
  26.                self: {
  27.                   href: "/api/v2/tasks?id=930789",
  28.                   method: "get"
  29.                }
  30.             }
  31.          },
  32.          {
  33.             id: 930776,
  34.             responsible_user_id: 504141,
  35.             created_by: 504141,
  36.             created_at: 1508659120,
  37.             updated_at: 1508659120,
  38.             account_id: 13667499,
  39.             group_id: 0,
  40.             element_type: 12,
  41.             element_id: 466791,
  42.             is_completed: false,
  43.             task_type: 1,
  44.             complete_till_at: 1508705940,
  45.             text: "Call Back",
  46.             result: [],
  47.             _links: {
  48.                self: {
  49.                   href: "/api/v2/tasks?id=930776",
  50.                   method: "get"
  51.                }
  52.             }
  53.          }
  54.       ]
  55.    }
  56. }