Leads

Leads can be viewed as an intermediary entity between the creation of Contacts, Accounts and Cases, and are a combination of interest data, Account data and Contact data. Leads exist solely as a single entity until it is accepted. Depending on the lead data, a contact, account and/or case can be created or updated.

Leads can currently only be created from external systems via the API, and not via the EASI'R frontend.

Another feature of leads are advanced escalation flows, primarily triggered by whether users in a team are acting on them: if users aren't processing leads quickly enough according to configurable rules, they can be escalated, and can be re-assigned to another team.

To avoid creating duplicate contacts and accounts, the EASI'R frontend will do a double entry search (using the Filters endpoints) with the data in the lead.

Lead statuses

A lead can have a different status depending on what has happened with the lead:

  1. assignable - The lead was created without a team ID, and can be assigned
  2. assigned - Lead is assigned to a team, and waiting to be processed. Has not been escalated or revoked
  3. rejected - Lead was rejected by a team member. Can be re-assigned in Agency
  4. accepted - Lead was accepted by a team, a contact, account and/or case was created or updated
  5. escalated - Lead was not acted upon within the allotted timeframe defined by the Lead Type. The lead is displayed for the team, but now also in Agency.
  6. called - Lead was escalated and in Agency then marked as "called", e.g. an Agency user contacted the dealership.
  7. revoked - Lead was called, but the team still did not start processing the lead within the allotted timeframe. The lead can now be reassigned in the Agency section, but is still shown to the Team until it's reassigned.
  8. expired - When a lead becomes older than the expires_at date and has not been accepted. The lead is still available through the API, but won't be shown to users in the assigned leads list.

The lifecycle of a Lead

1. Creation

Leads can be created with or without a team ID.

Having a team ID means that the lead is directly assigned to the specified team from creation.

No team ID means the Lead will be able to be assigned to a team using the Agency feature of EASI'R.

2. Assignment

Leads can be assigned (and reassigned) to different teams and users within EASI'R. After assignment, a lead can be accepted by a member of the team the lead was assigned to. If a lead is assigned to a specific user, it is only visible for that user (or admins), until it's escalated, at which point the lead becomes visible for the rest of the company or team.

Lead Type Settings control which users are notified (e-mail and/or in-app) of a new incoming lead.

After assignment, it may then be transferred to other teams via rejections (a user of the team rejects the lead instead of accepting it) or revocations.

3. Escalation

Escalations are enabled via the Lead Type. Only Leads in Lead Types that have escalation durations are escalated. The Lead Type defines escalation durations for the 2 escalation types in EASI'R: accept or activity.

  • accept: triggers when a dealer has not accepted the lead within the configured duration.
  • activity: triggers when a dealer has accepted the lead, but did not create any case activities after accepting the lead.

When a lead is escalated, its status is changed to escalated, and the following events occur:

  1. A notification is sent to the selected user(s) defined by the lead type. A team admin can configure which users are responsible for escalations.
  2. The lead is shown in Agency. An agency user can mark the lead as called if they have contacted the team to enquire why they are not working on the lead.
  3. If the lead has been assigned to a specific user, it's now visible for the whole team or company.

After the lead is marked as called, a new countdown begins: if the lead still isn't processed, it's marked as revoked.

When the lead is marked as revoked, in addition to being shown for the team, it is now also shown in Agency, where it can be re-assigned.

If an agency user re-assigns the lead, the Lead will cease to be visible for the Team, and the assignment process restarts.

4. Rejection

A user can reject the lead, for example if they do not carry a requested product in their catalog. The Lead will be marked as rejected and shown in the "Rejected" list in the Agency section, so it can be re-assigned.

5. Accepted

Accounts & Contacts

Depending on the data of the Lead, accounts and contacts can be updated or created.

If the Lead has an attached account_id or contact_id that already exists, and also has Account or Contact fixed and custom fields embedded, the existing Account or Contact is updated with this new data upon acceptation.

If there's no Account or Contact IDs, and only fixed and custom fields, accepting the Lead will trigger a double entry search (DES) in the frontend, which will search the Team's database for Account and/or Contacts with matching fields like email, phone and address in order to avoid duplicates.

After the DES, the user will have the choice of using the existing account/contact for creating a new case, or simply creating a new account and Contact to open the case with.

Cases

If there's no case open for the customer within the team, a new case is created.

If there is an open case, the lead details are added to this case.

The user is redirected to the case after acceptation.

If the lead was assigned to a specific user, the lead now becomes visible for the rest of the team or company.

6. Activities

The lifecycle of a lead stops when it has been accepted and an activity has been created in the case.

This means the Lead cannot become escalated nor revoked, and the lead cannot be re-assigned further.

Get leads

GET /leads

Query string parameters

  • groups integer - Comma separated list of ids.
  • lead_types - Comma separated list of UUIDs.
  • lead_sources string - Comma separated list.
  • status string - lead status
  • users integer - Comma separated list of ids.
  • teams integer - Comma separated list of ids.
  • start_at date
    • Y-m-d H:i:s format
  • end_at date
    • Y-m-d H:i:s format
    • Must be after start_at
  • Supports Pagination
  • Supports Sorting
    • Can be created_at, updated_at or external_weight
    • default: created_at

Response
Status code 200

Get leads by filter

POST /leads/filter

Requires admin right

Parameters

Payload

{
  "filter": [
    {
      "field": "lead.expires_at",
      "operator": "exists",
      "value": false
    }
  ]
}

Response
Status code 200

(Same response as GET /leads)

Get a specific lead

GET /leads/:lead_id

Response
Status code 200

Deprecated response fields

  • lead_type.relations_paths.is_sales_type will be removed from the response in 2019/11/01
{
  "id": "0b72c59a-93e6-497d-ba0f-3a4244bcb510",
  "company_id": 1,
  "user_id": 1,
  "team_id": 1,
  "team": {
    "id": 1,
    "name": "Sales Team West",
    "address_1": null,
    "address_2": null,
    "zip_code": null,
    "city": null,
    "state": null,
    "country": null,
    "phone_number": null,
    "website": null,
    "vat": null,
    "timezone": {
      "name": "Europe/London",
      "offset": 3600
    },
    "locale": {
      "code": "en-GB",
      "language_name": "English",
      "country": {
        "name": "United Kingdom",
        "native_name": "United Kingdom",
        "code": "GB"
      }
    },
    "team_type": "dealer",
    "group_id": 1,
    "created_at": "2014-01-01 12:45:56",
    "updated_at": "2016-05-13 12:03:35"
  },
  "agency_team_id": null,
  "lead_type_id": "2acb4738-dcd6-4e6e-aeb6-ed45ddeb9ab6",
  "lead_type": {
    "id": "2acb4738-dcd6-4e6e-aeb6-ed45ddeb9ab6",
    "name": "Magazine order",
    "icon": "offer",
    "entity_type": "leads",
    "team_id": null,
    "relations_paths": [
      {
        "id": "9eae431b-3d0f-4528-9c59-e9d1a40fcd04",
        "name": "Sales team north",
        "is_sales_type": true,
        "activity_types": {
          "milestones": [
            {
              "id": "a203539b-f06c-442c-8ad0-f5a56f0615f6",
              "name": "Contract",
              "sort_order": 1,
              "set_status": "closed",
              "suggest_task_after": 172800,
              "template_id": null,
              "content_suggestions": [],
              "extra_step": null,
              "additional_steps": [
                "product_details",
                "correspondence",
                "automations"
              ],
              "automated_communications": [],
              "chance_of_success": 100
            }
          ],
          "supportive": []
        },
        "created_at": "2015-03-04 11:51:19",
        "updated_at": "2015-03-04 11:51:19"
      }
    ],
    "escalation_accept": 86400,
    "escalation_activity": 86400,
    "escalation_ignore_weekends": false,
    "disabled": false,
    "highlighted": false,
    "team_settings": null,
    "created_at": "2016-05-06 18:42:38",
    "updated_at": "2016-05-10 00:28:30"
  },
  "b2c": false,
  "interest": "New HyperWasher Model",
  "product_ids": [
    "f066bc3e-347f-3768-a280-b24aab19318f",
    "c30d067b-24cf-3482-abb4-1cc57192da02"
  ],
  "lead_source": "Website",
  "lead_user": "Call Agency Co.",
  "lead_data": [
    {
      "key": "Product name",
      "value": "HyperWasher 9000 X"
    },
    {
      "key": "Product model",
      "value": "VSX-921"
    }
  ],
  "status": "accepted",
  "rejections": [
    {
      "team_id": 5,
      "user_id": 51,
      "rejection_reason": "This branch does not carry this product.",
      "rejection_date": "2016-05-10 21:34:11"
    }
  ],
  "acceptions": [
    {
      "team_id": 3,
      "user_id": 37,
      "case_id": "44e049a1-e9eb-476e-b14d-c4244cc8f727",
      "account_id": "03acbba8-2934-4826-b271-9c692b9a587c",
      "contact_id": "3ec6ab01-42c8-4db1-9ad2-76ef3bf1444b",
      "accepted_date": "2016-05-13 22:16:08",
      "first_activity_at": null
    },
    {
      "team_id": 1,
      "user_id": 1,
      "case_id": "44e049a1-e9eb-476e-b14d-c4244cc8f727",
      "account_id": "03acbba8-2934-4826-b271-9c692b9a587c",
      "contact_id": "3ec6ab01-42c8-4db1-9ad2-76ef3bf1444b",
      "accepted_date": "2016-05-16 13:00:08",
      "first_activity_at": "2016-05-16 13:04:11"
    }
  ],
  "assignments": [
    {
      "team_id": 5,
      "user_id": 51,
      "assignment_date": "2016-05-10 15:34:11"
    },
    {
      "team_id": 3,
      "user_id": 71,
      "assignment_date": "2016-05-13 15:22:17"
    },
    {
      "team_id": 1,
      "user_id": 1,
      "assignment_date": "2016-05-16 09:16:08"
    }
  ],
  "escalations": [
    {
      "team_id": 3,
      "escalation_type": "accept",
      "escalation_date": "2016-05-13 16:22:17"
    },
    {
      "team_id": 3,
      "escalation_type": "activity",
      "escalation_date": "2016-05-14 08:22:17"
    }
  ],
  "calls": [
    {
      "team_id": 27,
      "user_id": 223,
      "call_date": "2016-05-16 12:30:08"
    }
  ],
  "revocations": [
    {
      "team_id": 3,
      "escalation_type": "activity",
      "revocation_date": "2016-05-14 10:22:17"
    }
  ],
  "case_id": "5cdb4738-dcd6-4e6e-aeb6-ed45ddeb9ab6",
  "original_account": null,
  "account_id": "bb654738-dcd6-4e6e-bbd9-ed458789ab6",
  "account": {
    "fixed_fields": [
      {
        "id": 1,
        "type": "text",
        "name": "name",
        "label": "Name",
        "value": "Microsoft",
        "validation": null,
        "required": true,
        "hidden": false,
        "read_only": false,
        "sort_order": 0
      },
      {
        "id": 2,
        "type": "text",
        "name": "address",
        "label": "Address",
        "value": null,
        "validation": null,
        "required": false,
        "hidden": false,
        "read_only": false,
        "sort_order": 0
      },
      {
        "id": 3,
        "type": "text",
        "name": "zip_code",
        "label": "Zip code",
        "value": null,
        "validation": null,
        "required": false,
        "hidden": false,
        "read_only": false,
        "sort_order": 0
      },
      {
        "id": 4,
        "type": "text",
        "name": "city",
        "label": "City",
        "value": null,
        "validation": null,
        "required": false,
        "hidden": false,
        "read_only": false,
        "sort_order": 0
      },
      {
        "id": 5,
        "type": "text",
        "name": "state_region",
        "label": "State/Region",
        "value": null,
        "validation": null,
        "required": false,
        "hidden": false,
        "read_only": false,
        "sort_order": 0
      },
      {
        "id": 6,
        "type": "single_choice",
        "name": "country",
        "label": "Country",
        "value": null,
        "validation": null,
        "required": false,
        "hidden": false,
        "read_only": false,
        "sort_order": 0
      },
      {
        "id": 7,
        "type": "text",
        "name": "vat",
        "label": "VAT",
        "value": null,
        "validation": null,
        "required": false,
        "hidden": false,
        "read_only": false,
        "sort_order": 0
      },
      {
        "id": 8,
        "type": "text",
        "name": "website",
        "label": "Website",
        "value": null,
        "validation": "url",
        "required": false,
        "hidden": false,
        "read_only": false,
        "sort_order": 0
      }
    ],
    "custom_fields": null
  },
  "original_contact": null,
  "contact_id": "9ad54738-666a-4e6e-bbd9-ed458789ab6",
  "contact": {
    "fixed_fields": [
      {
        "id": 10,
        "type": "text",
        "name": "salutation",
        "label": "Salutation",
        "value": null,
        "validation": null,
        "required": false,
        "hidden": false,
        "read_only": false,
        "sort_order": 0
      },
      {
        "id": 11,
        "type": "text",
        "name": "first_name",
        "label": "First name",
        "value": "Bill",
        "validation": null,
        "required": true,
        "hidden": false,
        "read_only": false,
        "sort_order": 0
      },
      {
        "id": 12,
        "type": "text",
        "name": "last_name",
        "label": "Last name",
        "value": "Gates",
        "validation": null,
        "required": true,
        "hidden": false,
        "read_only": false,
        "sort_order": 0
      },
      {
        "id": 13,
        "type": "text",
        "name": "email",
        "label": "Email",
        "value": "bill.gates@microsoft.com",
        "validation": "email",
        "required": false,
        "hidden": false,
        "read_only": false,
        "sort_order": 0
      },
      {
        "id": 14,
        "type": "text",
        "name": "phone_number",
        "label": "Phone number",
        "value": "+1 0800-555-90210",
        "validation": null,
        "required": false,
        "hidden": false,
        "read_only": false,
        "sort_order": 0
      },
      {
        "id": 16,
        "type": "text",
        "name": "title",
        "label": "Title",
        "value": null,
        "validation": null,
        "required": false,
        "hidden": false,
        "read_only": false,
        "sort_order": 0
      }
    ],
    "custom_fields": null,
    "consent": {
      "call": {
        "consent_given": null,
        "updated_at": null
      },
      "letter": {
        "consent_given": true,
        "updated_at": "2017-02-25 12:34:56"
      },
      "email": {
        "consent_given": false,
        "updated_at": "2017-02-25 12:34:56"
      }
    }
  },
  "expires_at": null,
  "external_weight": 60,
  "notifications": {
    "assignment": {
      "suppress": false
    }
  },
  "escalates_at": "2017-05-09 09:16:07",
  "created_at": "2016-05-09 09:16:07",
  "updated_at": "2016-05-16 09:16:08"
}

Notes on original_account and original_contact:

If a lead has an account_id or contact_id, that account or contact is included using the original_account and original_contact fields.

Create a lead

POST /leads

Parameters

  • account_id UUID
    • Required without account
  • account object
    • Required without account_id
    • Supports Fields
      • Required
      • Matching resource Account
  • b2c boolean
    • Required
  • contact_id UUID
    • Required without contact
  • contact object
    • Required without contact_id
    • Supports Fields
      • Required
      • Matching resource Contact
  • contact.consent.{email,call,letter}.consent_given boolean|null - Allows overwriting consent information on the contact when lead is accepted. Not all types are required at once.
  • lead_source string - Free text field. Used to specify where the lead originated. For example, 'Website' or 'Conference'. Shown in the Details pane in the lead list in the frontend.
    • Required
  • lead_type_id UUID
    • Required
  • team_id integer - Which team to assign the lead to. If not set or null, lead can be assigned using Agency.
  • assigned_user_id integer - Which user to assign the lead to. Can be combined with team_id to limit visibility to team in case the lead is escalated.
  • agency_team_id integer - Which agency team is responsible for the lead, and handles escalations, reassignments, etc. for the lead.
    • Required without team_id
  • expires_at date - Defines a date whereupon the lead will become hidden - unable to be assigned and accepted.
  • interest string - Free text field. The primary interest of a lead. Could be a model number of a product, for example. Will be shown directly in the lead list shown to users in the frontend.
  • product_ids array
    • product_ids.* UUID
  • stock_vehicle_ids array
    • stock_vehicle_ids.* UUID
  • lead_data array - An array of objects containing key/value/type. See demonstration below. Used to add more detailed data than the interest field. Will be shown to users when clicking the Details button in the frontend.
    • Can contain b, strong, i, em, blockquote, br html tags
    • The type is optional (when left out it is string) and can be either table, heading or list
  • lead_user string - Free text field. An internal field used for filtering the 3rd party agencies who created the lead. Not shown in frontend.
  • external_weight integer - Can be used to sort the lead by urgency or business value, for example.
    • Between 1 and 100.
  • notifications.assignment.suppress boolean - Whether to suppress assignment notifications for the lead. Useful for avoiding excess notifications when creating many leads.

Lead Data No type: You can set a key, and a value. Both must be a string, but only the key is required.
Table: Value must be an array of arrays, with strings
List: Value must be an array with strings
Heading: Value must be a string

Payload

{
  "account": {
    "fixed_fields": [
      {
        "name": "name",
        "value": "Microsoft"
      }
    ]
  },
  "b2c": false,
  "contact": {
    "fixed_fields": [
      {
        "name": "first_name",
        "value": "Bill"
      },
      {
        "name": "last_name",
        "value": "Gates"
      },
      {
        "name": "email",
        "value": "bill.gates@microsoft.com"
      },
      {
        "name": "landline_phone_number",
        "value": "+1 0800-555-90210"
      },
      {
        "name": "mobile_phone_number",
        "value": "+1 0800-555-90210"
      }
    ],
    "custom_fields": [
      {
        "name": "sample_field",
        "value": true
      }
    ],
    "consent": {
      "call": {
        "consent_given": false
      },
      "letter": {
        "consent_given": true
      },
      "email": {
        "consent_given": false
      }
    }
  },
  "lead_source": "Website",
  "lead_type_id": "5661e4b4-8162-3cf5-9ed9-1373696af51a",
  "team_id": 2,
  "assigned_user_id": null,
  "agency_team_id": 2,
  "expires_at": "2017-06-26 12:23:01",
  "external_weight": 28,
  "notifications": {
    "assignment": {
      "suppress": false
    }
  },
  "lead_data": [
    {
      "key": "Product name",
      "value": "HyperWasher 9000 X"
    },
    {
      "key": "Product model",
      "value": "VSX-921"
    },
    {
      "type": "list",
      "value": [
          "Homepage",
          "Contact",
          "Product Details"
      ]
    },
    {
      "type": "table",
      "value": [
        ["The", "Header"],
        ["Row", "1"],
        ["Row", "2"],
        ["Row", "3"]
      ]
    },
    {
      "type": "heading",
      "value": "A heading"
    }
  ]
}

Response
Status code 201

{
  "id": "54d692af-3d49-4a85-9428-e525978e5d67",
  "company_id": 1,
  "user_id": 1,
  "assigned_user_id": null,
  "team_id": 2,
  "team": {
    "id": 2,
    "name": "Team 2",
    "address_1": "Savannah 123",
    "address_2": "Under the tree on the left",
    "zip_code": "4730",
    "city": "Umzimkulu",
    "state": "KwaZulu-Natal",
    "country": {
      "name": "South Africa",
      "native_name": "South Africa",
      "code": "ZA"
    },
    "phone_number": "031 308 7900",
    "website": "https:\/\/easir.com",
    "vat": "1234567890123456",
    "timezone": {
      "name": "Africa\/Johannesburg",
      "offset": 7200
    },
    "locale": {
      "code": "en-US",
      "language_name": "English",
      "country": {
        "name": "United States",
        "native_name": "United States",
        "code": "US"
      }
    },
    "team_type": null,
    "group_id": 1,
    "use_social_lookup": false,
    "created_at": "2014-01-01 12:45:56",
    "updated_at": "2014-01-02 00:11:22"
  },
  "agency_team_id": 2,
  "product_ids": [],
  "lead_type_id": "2acb4738-dcd6-4e6e-aeb6-ed45ddeb9ab6",
  "lead_type": {
    "id": "2acb4738-dcd6-4e6e-aeb6-ed45ddeb9ab6",
    "name": "Magazine order",
    "description": "offer",
    "group_id": null,
    "team_id": null,
    "escalation_accept": 86400,
    "escalation_activity": 86400,
    "disabled": false,
    "enable_escalation": false,
    "enable_team_settings": true,
    "team_settings": {
      "users": null,
      "disabled": false,
      "escalation_active": [
        {
          "day_of_week": 0,
          "closed": false,
          "open": "02:00:00",
          "close": "06:00:00"
        },
        {
          "day_of_week": 1,
          "closed": false,
          "open": "00:00:00",
          "close": "07:00:00"
        },
        {
          "day_of_week": 2,
          "closed": false,
          "open": "07:00:00",
          "close": "21:00:00"
        },
        {
          "day_of_week": 3,
          "closed": true,
          "open": "01:00:00",
          "close": "09:00:00"
        },
        {
          "day_of_week": 4,
          "closed": true,
          "open": "10:00:00",
          "close": "23:00:00"
        },
        {
          "day_of_week": 5,
          "closed": true,
          "open": "06:00:00",
          "close": "17:00:00"
        },
        {
          "day_of_week": 6,
          "closed": false,
          "open": "07:00:00",
          "close": "19:00:00"
        }
      ],
      "escalation_accept": 6414,
      "escalation_activity": 9912
    },
    "escalation_active": [
      {
        "day_of_week": 0,
        "closed": true,
        "open": "10:00:00",
        "close": "15:00:00"
      },
      {
        "day_of_week": 1,
        "closed": false,
        "open": "01:00:00",
        "close": "13:00:00"
      },
      {
        "day_of_week": 2,
        "closed": true,
        "open": "10:00:00",
        "close": "20:00:00"
      },
      {
        "day_of_week": 3,
        "closed": true,
        "open": "10:00:00",
        "close": "22:00:00"
      },
      {
        "day_of_week": 4,
        "closed": true,
        "open": "02:00:00",
        "close": "14:00:00"
      },
      {
        "day_of_week": 5,
        "closed": true,
        "open": "01:00:00",
        "close": "21:00:00"
      },
      {
        "day_of_week": 6,
        "closed": false,
        "open": "00:00:00",
        "close": "23:00:00"
      }
    ],
    "lead_count": 10,
    "escalates_at": "2017-06-24 06:46:54",
    "sort_order": 0,
    "created_at": "2017-06-12 17:49:29",
    "updated_at": "2017-06-16 21:50:14"
  },
  "b2c": false,
  "interest": null,
  "lead_source": "Website",
  "lead_user": "",
  "lead_data": [
    {
      "key": "Product name",
      "value": "HyperWasher 9000 X"
    },
    {
      "key": "Product model",
      "value": "VSX-921"
    },
    {
      "type": "list",
      "value": [
        "Homepage",
        "Contact",
        "Product Details"
      ]
    },
    {
      "type": "table",
      "value": [
        [
          "The",
          "Header"
        ],
        [
          "Row",
          "1"
        ],
        [
          "Row",
          "2"
        ],
        [
          "Row",
          "3"
        ]
      ]
    },
    {
      "type": "heading",
      "value": "A heading"
    }
  ],
  "status": "assigned",
  "rejections": [],
  "acceptions": [],
  "assignments": [],
  "escalations": [],
  "calls": [],
  "revocations": [],
  "team_deletions": [],
  "case_id": null,
  "original_account": null,
  "account_id": null,
  "account": {
    "fixed_fields": [
      {
        "id": 1,
        "type": "text",
        "name": "name",
        "label": "Name",
        "value": "Microsoft",
        "validation": null,
        "required": true,
        "hidden": false,
        "read_only": false,
        "sort_order": 0
      },
      {
        "id": 2,
        "type": "text",
        "name": "address",
        "label": "Address",
        "value": null,
        "validation": null,
        "required": false,
        "hidden": false,
        "read_only": false,
        "sort_order": 0
      },
      {
        "id": 3,
        "type": "text",
        "name": "zip_code",
        "label": "Zip code",
        "value": null,
        "validation": null,
        "required": false,
        "hidden": false,
        "read_only": false,
        "sort_order": 0
      },
      {
        "id": 4,
        "type": "text",
        "name": "city",
        "label": "City",
        "value": null,
        "validation": null,
        "required": false,
        "hidden": false,
        "read_only": false,
        "sort_order": 0
      },
      {
        "id": 5,
        "type": "text",
        "name": "state_region",
        "label": "State\/Region",
        "value": null,
        "validation": null,
        "required": false,
        "hidden": false,
        "read_only": false,
        "sort_order": 0
      },
      {
        "id": 6,
        "type": "single_choice",
        "name": "country",
        "label": "Country",
        "value": null,
        "validation": null,
        "required": false,
        "hidden": false,
        "read_only": false,
        "sort_order": 0
      },
      {
        "id": 7,
        "type": "text",
        "name": "vat",
        "label": "VAT",
        "value": null,
        "validation": null,
        "required": false,
        "hidden": false,
        "read_only": false,
        "sort_order": 0
      },
      {
        "id": 8,
        "type": "text",
        "name": "website",
        "label": "Website",
        "value": null,
        "validation": "url",
        "required": false,
        "hidden": false,
        "read_only": false,
        "sort_order": 0
      }
    ],
    "custom_fields": null
  },
  "original_contact": null,
  "contact_id": null,
  "contact": {
    "fixed_fields": [
      {
        "id": 10,
        "type": "text",
        "name": "salutation",
        "label": "Salutation",
        "value": null,
        "validation": null,
        "required": false,
        "hidden": false,
        "read_only": false,
        "sort_order": 0
      },
      {
        "id": 11,
        "type": "text",
        "name": "first_name",
        "label": "First name",
        "value": "Bill",
        "validation": null,
        "required": true,
        "hidden": false,
        "read_only": false,
        "sort_order": 0
      },
      {
        "id": 12,
        "type": "text",
        "name": "last_name",
        "label": "Last name",
        "value": "Gates",
        "validation": null,
        "required": true,
        "hidden": false,
        "read_only": false,
        "sort_order": 0
      },
      {
        "id": 13,
        "type": "text",
        "name": "email",
        "label": "Email",
        "value": "bill.gates@microsoft.com",
        "validation": "email",
        "required": false,
        "hidden": false,
        "read_only": false,
        "sort_order": 0
      },
      {
        "id": 14,
        "type": "text",
        "name": "landline_phone_number",
        "label": "Landline phone number",
        "value": "+1 0800-555-90210",
        "validation": null,
        "required": false,
        "hidden": false,
        "read_only": false,
        "sort_order": 0
      },
      {
        "id": 16,
        "type": "text",
        "name": "title",
        "label": "Title",
        "value": null,
        "validation": null,
        "required": false,
        "hidden": false,
        "read_only": false,
        "sort_order": 0
      },
      {
        "id": 35,
        "type": "text",
        "name": "mobile_phone_number",
        "label": "Mobile phone number",
        "value": "+1 0800-555-90210",
        "validation": null,
        "required": false,
        "hidden": false,
        "read_only": false,
        "sort_order": 0
      }
    ],
    "custom_fields": [
      {
        "id": 23465,
        "type": "boolean",
        "name": "sample_field",
        "label": "Custom Field Example",
        "value": true,
        "validation": null,
        "required": false,
        "hidden": false,
        "read_only": false,
        "sort_order": 0
      }
    ],
    "consent": {
      "call": {
        "consent_given": false,
        "updated_at": "2017-06-23 07:59:12"
      },
      "letter": {
        "consent_given": true,
        "updated_at": "2017-06-23 07:59:12"
      },
      "email": {
        "consent_given": false,
        "updated_at": "2017-06-23 07:59:12"
      }
    }
  },
  "expires_at": "2017-06-26 12:23:01",
  "escalates_at": "2017-06-24 06:46:54",
  "external_weight": 28,
  "notifications": {
    "assignment": {
      "suppress": false
    }
  }, 
  "created_at": "2017-06-23 07:59:12",
  "updated_at": "2017-06-23 07:59:12"
}

Update a lead

PUT /leads/:lead_id

Parameters

Payload

{
  "lead_type_id": "2acb4738-dcd6-4e6e-aeb6-ed45ddeb9ab6",
  "lead_source": "Lorem ipsum",
  "lead_data": [
    {
      "key": "Product model",
      "value": "2200X"
    }
  ],
  "b2c": false,
  "contact": {
    "fixed_fields": [
      {
        "name": "first_name",
        "value": "John"
      },
      {
        "name": "last_name",
        "value": "Doe"
      }
    ],
    "custom_fields": [
      {
        "id": "8",
        "value": "email@value.com"
      }
    ],
    "consent": {
      "call": {
        "consent_given": false,
      },
      "letter": {
        "consent_given": true,
      },
      "email": {
        "consent_given": false,
      }
    }
  },
  "account": {
    "fixed_fields": [
      {
        "id": "1",
        "value": "Name"
      }
    ]
  }
}

Response
Status code 200

{
  "id": "165ab7f2-1ff2-4c47-a674-9c298a4e9909",
  "company_id": 1,
  "user_id": 1,
  "team_id": 1,
  "team": {
    "id": 1,
    "name": "Team 1",
    "address_1": "Savannah 123",
    "address_2": "Under the tree on the left",
    "zip_code": "4730",
    "city": "Umzimkulu",
    "state": "KwaZulu-Natal",
    "country": {
      "name": "South Africa",
      "native_name": "South Africa",
      "code": "ZA"
    },
    "phone_number": "031 308 7900",
    "website": "https:\/\/easir.com",
    "vat": "1234567890123456",
    "timezone": {
      "name": "Africa\/Johannesburg",
      "offset": 7200
    },
    "locale": {
      "code": "en-US",
      "language_name": "English",
      "country": {
        "name": "United States",
        "native_name": "United States",
        "code": "US"
      }
    },
    "team_type": null,
    "group_id": 1,
    "use_social_lookup": false,
    "created_at": "2014-01-01 12:45:56",
    "updated_at": "2014-01-02 00:11:22"
  },
  "agency_team_id": 1,
  "lead_type_id": "2acb4738-dcd6-4e6e-aeb6-ed45ddeb9ab6",
  "lead_type": {
    "id": "2acb4738-dcd6-4e6e-aeb6-ed45ddeb9ab6",
    "name": "Magazine order",
    "description": "offer",
    "group_id": null,
    "team_id": null,
    "escalation_accept": 86400,
    "escalation_activity": 86400,
    "disabled": false,
    "enable_escalation": false,
    "enable_team_settings": true,
    "team_settings": {
      "users": null,
      "disabled": false,
      "escalation_active": [
        {
          "day_of_week": 0,
          "closed": true,
          "open": "08:45:33",
          "close": "20:49:55"
        },
        {
          "day_of_week": 1,
          "closed": true,
          "open": "23:35:13",
          "close": "08:45:20"
        },
        {
          "day_of_week": 2,
          "closed": false,
          "open": "23:28:34",
          "close": "10:15:40"
        },
        {
          "day_of_week": 3,
          "closed": true,
          "open": "07:19:41",
          "close": "18:11:43"
        },
        {
          "day_of_week": 4,
          "closed": false,
          "open": "06:32:31",
          "close": "04:32:37"
        },
        {
          "day_of_week": 5,
          "closed": true,
          "open": "09:38:21",
          "close": "16:25:41"
        },
        {
          "day_of_week": 6,
          "closed": false,
          "open": "12:09:56",
          "close": "18:05:40"
        }
      ],
      "escalation_accept": 52958,
      "escalation_activity": 19673
    },
    "escalation_active": [
      {
        "day_of_week": 0,
        "closed": false,
        "open": "09:44:33",
        "close": "16:56:20"
      },
      {
        "day_of_week": 1,
        "closed": false,
        "open": "06:44:12",
        "close": "13:01:54"
      },
      {
        "day_of_week": 2,
        "closed": false,
        "open": "03:40:12",
        "close": "16:56:52"
      },
      {
        "day_of_week": 3,
        "closed": false,
        "open": "13:16:54",
        "close": "18:30:09"
      },
      {
        "day_of_week": 4,
        "closed": false,
        "open": "19:15:50",
        "close": "21:10:17"
      },
      {
        "day_of_week": 5,
        "closed": true,
        "open": "09:01:51",
        "close": "01:57:42"
      },
      {
        "day_of_week": 6,
        "closed": false,
        "open": "09:26:53",
        "close": "07:40:34"
      }
    ],
    "lead_count": 8,
    "escalates_at": "2017-05-06 08:51:32",
    "sort_order": 0,
    "created_at": "2017-04-26 08:14:07",
    "updated_at": "2017-05-02 04:56:40"
  },
  "b2c": false,
  "interest": null,
  "product_ids": [],
  "lead_source": "Lorem ipsum",
  "lead_user": "",
  "lead_data": [
    {
      "value": "2200X",
      "key": "Product model"
    }
  ],
  "status": "assigned",
  "rejections": [],
  "acceptions": [],
  "assignments": [
    {
      "team_id": 1,
      "user_id": 1,
      "assignment_date": "2017-04-30 08:51:32"
    }
  ],
  "escalations": [],
  "calls": [],
  "revocations": [],
  "team_deletions": [],
  "case_id": null,
  "original_account": null,
  "account_id": null,
  "account": {
    "fixed_fields": [
      {
        "id": 1,
        "type": "text",
        "name": "name",
        "label": "Name",
        "value": "Name",
        "validation": null,
        "required": true,
        "hidden": false,
        "read_only": false,
        "sort_order": 0
      },
      {
        "id": 2,
        "type": "text",
        "name": "address",
        "label": "Address",
        "value": null,
        "validation": null,
        "required": false,
        "hidden": false,
        "read_only": false,
        "sort_order": 0
      },
      {
        "id": 3,
        "type": "text",
        "name": "zip_code",
        "label": "Zip code",
        "value": null,
        "validation": null,
        "required": false,
        "hidden": false,
        "read_only": false,
        "sort_order": 0
      },
      {
        "id": 4,
        "type": "text",
        "name": "city",
        "label": "City",
        "value": null,
        "validation": null,
        "required": false,
        "hidden": false,
        "read_only": false,
        "sort_order": 0
      },
      {
        "id": 5,
        "type": "text",
        "name": "state_region",
        "label": "State\/Region",
        "value": null,
        "validation": null,
        "required": false,
        "hidden": false,
        "read_only": false,
        "sort_order": 0
      },
      {
        "id": 6,
        "type": "single_choice",
        "name": "country",
        "label": "Country",
        "value": null,
        "validation": null,
        "required": false,
        "hidden": false,
        "read_only": false,
        "sort_order": 0
      },
      {
        "id": 7,
        "type": "text",
        "name": "vat",
        "label": "VAT",
        "value": null,
        "validation": null,
        "required": false,
        "hidden": false,
        "read_only": false,
        "sort_order": 0
      },
      {
        "id": 8,
        "type": "text",
        "name": "website",
        "label": "Website",
        "value": null,
        "validation": "url",
        "required": false,
        "hidden": false,
        "read_only": false,
        "sort_order": 0
      }
    ],
    "custom_fields": null
  },
  "original_contact": null,
  "contact_id": null,
  "contact": {
    "fixed_fields": [
      {
        "id": 10,
        "type": "text",
        "name": "salutation",
        "label": "Salutation",
        "value": null,
        "validation": null,
        "required": false,
        "hidden": false,
        "read_only": false,
        "sort_order": 0
      },
      {
        "id": 11,
        "type": "text",
        "name": "first_name",
        "label": "First name",
        "value": "John",
        "validation": null,
        "required": true,
        "hidden": false,
        "read_only": false,
        "sort_order": 0
      },
      {
        "id": 12,
        "type": "text",
        "name": "last_name",
        "label": "Last name",
        "value": "Doe",
        "validation": null,
        "required": true,
        "hidden": false,
        "read_only": false,
        "sort_order": 0
      },
      {
        "id": 13,
        "type": "text",
        "name": "email",
        "label": "Email",
        "value": null,
        "validation": "email",
        "required": false,
        "hidden": false,
        "read_only": false,
        "sort_order": 0
      },
      {
        "id": 14,
        "type": "text",
        "name": "landline_phone_number",
        "label": "Landline phone number",
        "value": null,
        "validation": null,
        "required": false,
        "hidden": false,
        "read_only": false,
        "sort_order": 0
      },
      {
        "id": 16,
        "type": "text",
        "name": "title",
        "label": "Title",
        "value": null,
        "validation": null,
        "required": false,
        "hidden": false,
        "read_only": false,
        "sort_order": 0
      },
      {
        "id": 35,
        "type": "text",
        "name": "mobile_phone_number",
        "label": "Mobile phone number",
        "value": null,
        "validation": null,
        "required": false,
        "hidden": false,
        "read_only": false,
        "sort_order": 0
      }
    ],
    "custom_fields": [
      {
        "id": 8,
        "type": "text",
        "name": "email",
        "label": "Custom E-mail",
        "value": "email@value.com",
        "validation": "email",
        "required": false,
        "hidden": false,
        "read_only": false,
        "sort_order": 0
      },
      {
        "id": 9,
        "type": "numeric",
        "name": "number",
        "label": "Custom Number",
        "value": null,
        "validation": "numeric",
        "required": false,
        "hidden": false,
        "read_only": false,
        "sort_order": 0
      },
      {
        "id": 10,
        "type": "date",
        "name": "date",
        "label": "Custom Date",
        "value": null,
        "validation": "date",
        "required": false,
        "hidden": false,
        "read_only": false,
        "sort_order": 0
      },
      {
        "id": 11,
        "type": "single_choice",
        "name": "single_choice",
        "label": "Custom Single Choice",
        "value": null,
        "validation": null,
        "required": false,
        "hidden": false,
        "read_only": false,
        "sort_order": 0
      },
      {
        "id": 12,
        "type": "multiple_choice",
        "name": "multiple_choice",
        "label": "Custom Multiple Choice",
        "value": null,
        "validation": null,
        "required": false,
        "hidden": false,
        "read_only": false,
        "sort_order": 0
      }
    ],
    "consent": {
      "call": {
        "consent_given": false,
        "updated_at": "2017-05-08 11:22:06"
      },
      "letter": {
        "consent_given": true,
        "updated_at": "2017-05-08 11:22:06"
      },
      "email": {
        "consent_given": false,
        "updated_at": "2017-05-08 11:22:06"
      }
    }
  },
  "expires_at": null,
  "escalates_at": "2017-05-06 08:51:32",
  "external_weight": null,
  "notifications": {
    "assignment": {
      "suppress": false
    }
  },
  "created_at": "2017-04-29 08:51:32",
  "updated_at": "2017-05-08 11:22:06"
}

Accept a lead

PUT /leads/:lead_id/accept

Finishes the creation of the lead, creating and/or updating the account and/or contact.

You can specify account, contact ids to overwrite the existing IDs, or update your existing entities.

Errors

  • leads.no_team: You are not a part of a team
  • leads.accepted: Lead was already accepted
  • leads.invalid_account: The lead has a non-existing account ID. Please provide an account ID when creating the lead.
  • lead.no_account: Either account or account ID is required.
  • leads.invalid_contact: The lead has a non-existing contact ID. Please provide a contact ID when creating the lead.
  • lead.no_contact: A lead should have a contact to be accepted.
  • validation.accepting_lead.user_id_mismatch: User_id cannot be passed when case_id is also passed.

Parameters

  • contact_id UUID
  • account_id UUID
    • Required with contact_id
  • user_id integer
  • case_id UUID
  • relations_path_id UUID
    • Required without case_id
  • overwrite_fields boolean - whether to overwrite any fields present in both Lead and Account/Contact. Non-existing fields are still appended.
    • default true

Payload

{
  "account_id": "3cb87c2f-0feb-3b10-90a1-b5d01bb3eb69",
  "contact_id": "8dbb05f9-e19c-34f8-8885-eed4e520bf3c",
  "relations_path_id": "9eae431b-3d0f-4528-9c59-e9d1a40fcd04",
  "overwrite_fields": true
}

Accept a lead for a specific user

{
  "relations_path_id": "9eae431b-3d0f-4528-9c59-e9d1a40fcd04",
  "user_id": 4
}

Accept a lead on an existing case

{
  "case_id": "81aceb2a-f9b2-3b4a-b5dd-d9cfeadbd24d"
}

Response
Status code 200

After accepting the lead, an object containing the created or edited case, the account and the contact is added to the acceptions array.

{
  "id": "4b20af04-a774-425e-b82d-44d9a6b3f4d9",
  "user_id": 0,
  "team_id": 1,
  "lead_types": [
    "6c5ad1df-8ed8-4a6e-b805-56e1ce8b95a0"
  ],
  "b2c": false,
  "interest": null,
  "lead_source": "This is a test",
  "lead_data": [
    {
      "key": "Product model",
      "value": "2200X"
    }
  ],
  "rejections": null,
  "acceptions": [
    {
      "team_id": 1,
      "user_id": 1,
      "case_id": "44e049a1-e9eb-476e-b14d-c4244cc8f727",
      "account_id": "03acbba8-2934-4826-b271-9c692b9a587c",
      "contact_id": "3ec6ab01-42c8-4db1-9ad2-76ef3bf1444b",
      "accepted_date": "2015-05-19T13:58:27.349Z"
    }
  ],
  "assignments": [
    {
      "team_id": 1,
      "user_id": 1,
      "assignment_date": "2015-05-19T13:57:00+0000"
    }
  ],
  "escalations": null,
  "case_id": "44e049a1-e9eb-476e-b14d-c4244cc8f727",
  "account_id": "03acbba8-2934-4826-b271-9c692b9a587c",
  "account": {
    "fixed_fields": [
      {
        "field_id": 1,
        "text_value": "Name"
      }
    ],
    "custom_fields": []
  },
  "contact_id": "3ec6ab01-42c8-4db1-9ad2-76ef3bf1444b",
  "contact": {
    "fixed_fields": [
      {
        "field_id": 11,
        "text_value": "John"
      },
      {
        "field_id": 12,
        "text_value": "Doe"
      }
    ],
    "custom_fields": [
      {
        "field_id": 8,
        "text_value": "email@value.com"
      }
    ]
  },
  "external_weight": null,
  "notifications": {
    "assignment": {
      "suppress": false
    }
  },
  "created_at": "2015-05-19 13:57:00",
  "updated_at": "2015-05-19 13:57:00"
}

Reject a lead

PUT /leads/:lead_id/reject

Parameters

  • reason string

Payload

{
  "reason": "We do not sell this product."
}

Response
Status code 200

Delete a lead

DELETE /leads/:lead_id

Requires the Agency user right

Response
Status code 204