Task for batch import and engaging profiles in the scenario

Description

Adding or updating multiple profiles and then sending them to the scenario. Returns a response with the task id without waiting for execution.

note

The request body is limited by default to 10mb, exception: files are 100mb.

It is not recommended to transmit more than 10,000 profiles per request.

Data field rules

The rules apply to the data object inside each element of the data array.

• The field value must be valid for the field type: numeric fields accept a number, "list" fields accept a variant name from the list or its ordinal number, etc. If the value does not match the field type (for example, a string that is not in the list of variants is passed to a list field), the request returns an error. Value formats for custom fields are listed in the Custom field value formats section.
• Only the fields explicitly passed in the data object inside each element of the data array are updated. If some profile fields should not change, do not pass them in the request.
• Each profile in the data array is processed independently: if a field value in one profile fails validation, that profile is not imported and not sent to the scenario, while the remaining profiles are processed. The error for this profile is reflected in the task result.
• For more flexible field value management, use database fields functional update.

URL

Method: POST

https://example.com/api/v1.1/workflows/import_and_start_batch_task

Request parameters

Parameter	Type	Example	Required	Description
workflow_id	Int	1	Yes	Workflow identifier
high_priority	bool	true	No	Overrides the processing priority of the created task. If not specified, the scenario's priority is used. See High-priority scenarios
matching	String	"email"	Yes	Profile matching mode. By default – email.
profile_id	String	"5f19953a03e4227216278ba4"	"matching":"profile_id"	Profile identifier
email	String	"importStart9219@example.com"	"matching":"email" - from profile or subscriptions "matching":"email_profile" - only from profile	Email
phone	String	"+79001234567"	"matching":"phone"	Phone number
field_name	String	"CRM_ID"	"matching":"custom"	The name of the custom profile field for search.
field_value	Any	"12345"	"matching":"custom"	The value of the custom profile field for search. Search by combination of tags is available. Values are recorded as a string: "tag-1, tag-2".
data	Object	{    "_fname": "John",    "_lname": "Doe" }	No	Profile data, including subscriptions
skip_triggers	Bool	true	No	Skip triggers and workflows activated by import and update actions By default – false
skip_invalid_subscriptions	Bool	true	No	Skip invalid subscriptions By default – false
detect_geo	Bool	true	No	Detect geolocation by IP (it is detected by data from the fields _regip or _ip)
content	Object	"content":{    "one": "My email = importStart9219@example.com",    "two": "Timestamp: 1595512477",    "three": "Three" }	No	Additional data to be used in the message template as {apicontent.fieldname} variable. The variable can be used in the "API call" and "API content filter" nodes
custom_data	JSON object	"custom_data": {    "field": "value", }	No	Add some data to be used in Action hooks. The parameter can be passed either at the root of the request or separately in each data object.
attach	array of {name, flie_key, data, mimetype}		No	File to attach to an Email message (only for Email triggers)

Returned parameters

Parameter	Type	Description
error_text	string	Error text
error	int	Error code
task_id	string	Task identifier

Request example – "matching":"email"

JSON

{
  "workflow_id": 12,
  "matching": "email",
  "data": [
    {
      "data": {
        "_fname": "Herbert",
        "_lname": "Lambert",
        "email": "example@example.com",
        "phones": "+79862014852"
      }
    },
    {
      "data": {
        "_fname": "Bert",
        "_lname": "Lambert",
        "email": "example@example.com",
        "phones": "+79862014853"
      }
    }
  ]
}

XML

<xml>
  <workflow_id>12</workflow_id>
  <matching>email</matching>
  <data>
      <_fname>Herb</_fname>
      <_lname>Limbert</_lname>
      <email>example@example.com</email>
      <phones>+79847076617</phones>
  </data>
  <data>
      <_fname>Bert</_fname>
      <_lname>Limbert</_lname>
      <email>example@example.com</email>
      <phones>+79817076617</phones>
  </data>
</xml>   

Request example – "matching":"custom"

JSON

{
    "workflow_id": 12,
    "matching": "custom",
    "field_name": "New_field_7",
    "data": [
        {
            "data": {
                "_fname": "Kristina",
                "_lname": "Lambert",
                "email": "example@example.com",
                "phones": "+79568150395",
                "New_field_7": "00015"
            }
        },
        {
            "data": {
                "_fname": "Christopher",
                "_lname": "Lambert",
                "email": "example@example.com",
                "phones": "+79568150396",
                "New_field_7": "00016"
            }
        }
    ]
}

XML

<xml>
    <workflow_id>12</workflow_id>
    <matching>custom</matching>
    <field_name>CRM_ID</field_name>
    <data>
        <_fname>Naomy</_fname>
        <_lname>Depp</_lname>
        <email>example@example.com</email>
        <phones>+798144890880</phones>
        <CRM_ID>7830</CRM_ID>
    </data>
    <data>
        <_fname>Nataly</_fname>
        <_lname>Depp</_lname>
        <email>example@example.com</email>
        <phones>+73755334351</phones>
        <CRM_ID>0934</CRM_ID>
    </data>
</xml>

Response example

JSON

{
  "error": 0,
  "error_text": "Successful operation",
  "task_id": "30421978-7f6d-4f39-913f-fb6cad8e2477"
}

XML

<xml>
    <error>0</error>
    <error_text>Successful operation</error_text>
    <task_id>675231ce-63b4-4bca-a153-10d87b938d26</task_id>
</xml>

Example of a response when a request restriction is triggered

JSON

{
  "error": 400,
  "error_debug": "http: request body too large",
  "error_text": "Invalid request"
}

XML

<xml>
  <error>400</error>
  <error_debug>http: request body too large</error_debug>
  <error_text>Invalid request</error_text>
</xml>

Checking the status of the task

URL

Method: POST

https://example.com/api/v1.1/tasks/status

Request parameters

Parameter	Type	Example	Required	Description
task_id	string	"task_b2f9fk6a-2479-4a63-b592-f15d4e3b69c5"	Yes	Task ID

Request example

JSON

{
  "task_id": "task_b2f9fk6a-2479-4a63-b592-f15d4e3b69c5"        
}

XML

<xml>
  <task_id>task_b2f9fk6a-2479-4a63-b592-f15d4e3b69c5</task_id>
</xml>

Response example

JSON

{
    "data": {
        "status": "completed",
        "progress": 100,
        "result": {
            "error": 0,
            "error_text": "",
            "result": [
                {
                    "profile_id": "61e947333f62fc26d384452c"
                },
                {
                    "profile_id": "61e947333f62fc26d384452e"
                }
            ]
        }
    },
    "error": 0,
    "error_text": "Successful operation"
}

XML

<xml>
    <data>
        <status>completed</status>
        <progress>100</progress>
        <result>
            <error>0</error>
            <error_text></error_text>
            <result>
                <profile_id>61e947333f62fc26d384452c</profile_id>
            </result>
            <result>
                <profile_id>61e947333f62fc26d384452e</profile_id>
            </result>
        </result>
    </data>
    <error>0</error>
    <error_text>Successful operation</error_text>
</xml>