Skip to content

Leads API

Warning

This functionality has been deprecated in the new giosg script v2 that has been set as a standard from Dec. 16th - 2021 onwards.

Please take a look at Interaction Builder as an alternative to this functionality when your organization's settings does not include this.

Leads

Lead forms can be used to gather information about the potential lead. Leads can be processed by using Lead API.

A lead object has the following attributes::

Attribute Type Editable Description
id UUID read-only Unique identifier of this lead.
lead_form_id UUID read-only ID of the lead form.
organization_id UUID read-only ID of the organization which owns the lead.
room_id UUID read-only ID of the room in which the lead was gathered.
assigned_user_id UUID optional ID of the user who is responsible to handle this lead. null if no user is assigned to handle this lead. This field normally changed as the user's id who picked lead in swimlane.
assigned_user object read-only The user object.
visitor_id string read-only ID of the visitor.
is_closed boolean optional Whether the lead has been closed or not.
is_processable boolean read-only true if lead is meant to be processed by third party application, false if it's shown in the Console.
page_url string read-only The url of the page where the lead was collected.
page_title string read-only The title of the page where the lead was collected.
data object read-only The data which was collected in lead form. Data object's keys are names of the collected fields and values are from corresponding field. The object only consists of fields which visitor has filled, this might cause some keys to be missing if the visitor did not provide anything to these fields.
created_at datetime read-only When the lead was created.
updated_at datetime read-only When the lead was last time updated.
closed_at datetime read-only When the lead was closed.
sensitive_data_purged_at datetime read-only When the lead's sensitive data was purged. This means that the data is set to as an empty object. This is null if the data was not purged.

List organization's leads

You can get a paginated collection of all leads for the organization. They are sorted by the creation time of the lead, in ascending order.

This endpoint takes the following GET-parameters:

Parameter Type Default Description
ordering ordering created_at Ordering of results with options created_at or -created_at
is_processable boolean (none) If true, then return only leads which are processed by third party. If false, return only leads which are shown in the Console.

GET /api/v5/orgs/<organization_id>/leads

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization

Retrieve organization's lead's details

You may retrieve a single lead object by its ID (<lead_id>) that organization (<organization_id>) is eligible for:

GET /api/v5/orgs/<organization_id>/leads/<lead_id>

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
  • 404 if lead was not found

Update organization's lead's details

You may update your organization's leads by:

PUT /api/v5/orgs/<organization_id>/leads/<lead_id>

PATCH /api/v5/orgs/<organization_id>/leads/<lead_id>

This endpoint returns:

  • 200 if the request was successful
  • 400 if required attributes are missing from the request
  • 400 if the request payload is in wrong format
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
  • 404 if lead was not found

List user's assigned leads

1
GET https://service.giosg.com/api/v5/users/ac83d426-be80-4d75-8c62-49a77f98468e/assigned_leads

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
{
  "next": "https://service.giosg.com/api/v5/users/ac83d426-be80-4d75-8c62-49a77f98468e/leads",
  "previous": null,
  "results": [
    {
      "id": "4d0648b8-9074-11e6-963e-f45c89c72de3",
      "lead_form_id": "700f38ba-9529-11e6-b202-f45c89c72de3",
      "organization_id": "7c99425e-9529-11e6-8107-f45c89c72de3",
      "room_id": "9f3d51a8-9529-11e6-80e7-f45c89c72de3",
      "assigned_user_id": "ac83d426-be80-4d75-8c62-49a77f98468e",
      "assigned_user": {
        "id": "ac83d426-be80-4d75-8c62-49a77f98468e",
        "full_name": "Bill Giosg",
        "first_name": "Bill",
        "last_name": "Giosg",
        "organization_id": "7c99425e-9529-11e6-8107-f45c89c72de3"
      },
      "visitor_id": "08119566026a4e1194a7a3244c90f925",
      "is_closed": false,
      "is_processable": false,
      "page_url": "https://giosg.com",
      "page_title": "Giosg - intelligent conversion marketing platform",
      "data": {
        "phone": "+123654789",
        "name": "Lead Man",
        "email": "lead.man@superheroes.gov"
      },
      "created_at": "2016-09-01T11:31:36.042Z",
      "updated_at": "2016-09-01T15:31:36.042Z",
      "closed_at": null,
      "sensitive_data_purged_at": null
    }
  ]
}

You can get a paginated collection of all assigned leads for the user. They are sorted by the creation time of the lead, in ascending order.

This endpoint takes the following GET-parameters:

Parameter Type Default Description
ordering ordering created_at Ordering of results with options created_at or -created_at
is_processable boolean (none) If true, then return only leads which are processed by third party. If false, return only leads which are shown in the Console.

GET /api/v5/users/<user_id>/assigned_leads

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the user

List user's pending leads

You can get a paginated collection of all pending leads for the user. They are sorted by the creation time of the lead, in ascending order.

This endpoint takes the same GET-parameters as the other list endpoints.

GET /api/v5/users/<user_id>/pending_leads

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the user

Retrieve user's lead's details

Example request for retrieving pending lead's details

1
GET https://service.giosg.com/api/v5/users/ac83d426-be80-4d75-8c62-49a77f98468e/pending_leads/4d0648b8-9074-11e6-963e-f45c89c72de3

Example response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
  "id": "4d0648b8-9074-11e6-963e-f45c89c72de3",
  "lead_form_id": "700f38ba-9529-11e6-b202-f45c89c72de3",
  "organization_id": "7c99425e-9529-11e6-8107-f45c89c72de3",
  "room_id": "9f3d51a8-9529-11e6-80e7-f45c89c72de3",
  "assigned_user_id": null,
  "assigned_user": null,
  "visitor_id": "08119566026a4e1194a7a3244c90f925",
  "is_closed": false,
  "is_processable": false,
  "page_url": "https://giosg.com",
  "page_title": "Giosg - intelligent conversion marketing platform",
  "data": {
    "phone": "+123654789",
    "name": "Lead Man",
    "email": "lead.man@superheroes.gov"
  },
  "created_at": "2016-09-01T11:31:36.042Z",
  "updated_at": "2016-09-01T15:31:36.042Z",
  "closed_at": null,
  "sensitive_data_purged_at": null
}

You may retrieve a single lead object by its ID (<lead_id>) that user (<user_id>) is eligible for. Assigned leads by:

GET /api/v5/users/<user_id>/assigned_leads/<lead_id>

And pending leads:

GET /api/v5/users/<user_id>/pending_leads/<lead_id>

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the user
  • 404 if lead was not found

Update user's lead's details

Example request that updates pending lead to be handled by user.

1
PATCH https://service.giosg.com/api/v5/users/ac83d426-be80-4d75-8c62-49a77f98468e/pending_leads/f8a3917d-9073-11e6-b96f-f45c89c72de3

1
2
3
{
  "assigned_user_id": "ac83d426-be80-4d75-8c62-49a77f98468e"
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
{
  "id": "4d0648b8-9074-11e6-963e-f45c89c72de3",
  "lead_form_id": "700f38ba-9529-11e6-b202-f45c89c72de3",
  "organization_id": "7c99425e-9529-11e6-8107-f45c89c72de3",
  "room_id": "9f3d51a8-9529-11e6-80e7-f45c89c72de3",
  "assigned_user_id": "ac83d426-be80-4d75-8c62-49a77f98468e",
  "assigned_user": {
    "id": "ac83d426-be80-4d75-8c62-49a77f98468e",
    "full_name": "Bill Giosg",
    "first_name": "Bill",
    "last_name": "Giosg",
    "organization_id": "7c99425e-9529-11e6-8107-f45c89c72de3"
  },
  "visitor_id": "08119566026a4e1194a7a3244c90f925",
  "is_closed": false,
  "is_processable": false,
  "page_url": "https://giosg.com",
  "page_title": "Giosg - intelligent conversion marketing platform",
  "data": {
    "phone": "+123654789",
    "name": "Lead Man",
    "email": "lead.man@superheroes.gov"
  },
  "created_at": "2016-09-01T11:31:36.042Z",
  "updated_at": "2016-09-01T15:31:36.042Z",
  "closed_at": null,
  "sensitive_data_purged_at": null
}

You may update your assigned leads by:

PUT /api/v5/users/<user_id>/assigned_leads/<lead_id>

PATCH /api/v5/users/<user_id>/assigned_leads/<lead_id>

And pending leads:

PUT /api/v5/users/<user_id>/pending_leads/<lead_id>

PATCH /api/v5/users/<user_id>/pending_leads/<lead_id>

These endpoint returns:

  • 200 if the request was successful
  • 400 if required attributes are missing from the request
  • 400 if the request payload is in wrong format
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the user
  • 404 if lead was not found