Skip to content

Goals API

Goals

Goals are events that can be triggered for a visitor. Goals are used for reporting and for Targeting.

A goal object contains the following attributes.

Attribute Type Editable Description
id UUID read-only UUID string identifier
name string required Human readable name of the goal.
organization_id UUID read-only The ID of the owner organization
organization object read-only The organization who owns this team.
is_any_room_allowed boolean required Can this goal match in any room
allowed_rooms array of UUID required If is_any_room_allowed is false then this goal can match only in the allowed_rooms. Allowed rooms only allows rooms that the organization owns. Organization's rooms can be fetched using the Rooms API
default_value float optional Default value of the goal. For example 14.15
conditions array of objects  required List of rule conditions that are used for matching this goal.
created_at datetime read-only When the goal was created
created_by_user_id UUID read-only The ID of the user who created this goal
created_by_user object read-only The user resource who created this goal
updated_at datetime read-only When the goal name or description was last time updated
updated_by_user_id UUID read-only The ID of the user who last time updated this goal
updated_by_user object read-only The user resource who last time updated this goal

List goals for organization

Get a paginated collection of all the goals of your organization:

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

 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
35
36
37
38
39
40
41
42
43
44
45
46
{
  "next": "https://service.giosg.com/api/v5/orgs/ac83d426-be80-4d75-8c62-49a77f98468e/goals",
  "previous": null,
  "results": [
    {
      "id": "4d0648b8-9074-11e6-963e-f45c89c72de3",
      "name": "User sent a lead",
      "allowed_rooms": ["e6a850ca-e1d3-11e4-9706-38b1dbe48b5b"],
      "allow_any_room": false,
      "default_value": "10.00",
      "conditions": [
        {
          "negate": false,
          "settings": {},
          "type": 27,
          "value": ""
        }
      ],
      "organization_id": "ac83d426-be80-4d75-8c62-49a77f98468e",
      "organization": {
        "id": "ac83d426-be80-4d75-8c62-49a77f98468e",
        "name": "Example Ltd."
      },
      "created_by_user_id": "ac83d426-be80-4d75-8c62-49a77f98468e",
      "created_by_user": {
        "id": "ac83d426-be80-4d75-8c62-49a77f98468e",
        "full_name": "Bill Giosg",
        "first_name": "Bill",
        "last_name": "Giosg",
        "organization_id": "ac83d426-be80-4d75-8c62-49a77f98468e",
        "is_bot": false
      },
      "created_at": "2016-09-01T11:31:36.042Z",
      "updated_at": "2016-09-01T15:31:36.042Z",
      "updated_by_user_id": "ac83d426-be80-4d75-8c62-49a77f98468e",
      "updated_by_user": {
        "id": "ac83d426-be80-4d75-8c62-49a77f98468e",
        "full_name": "Bill Giosg",
        "first_name": "Bill",
        "last_name": "Giosg",
        "organization_id": "ac83d426-be80-4d75-8c62-49a77f98468e",
        "is_bot": false
      }
    }
  ]
}

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

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
  • 403 if you do not have settings permission

Creating a new goal

POST /api/v5/orgs/<organization_id>/goals

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
  "name": "A new goal",
  "allow_any_room": true,
  "allowed_rooms": [],
  "conditions": [
    {
      "negate": false,
      "settings": {},
      "type": 1,
      "value": "Helsinki"
    }
  ]
}

This endpoint returns:

  • 201 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
  • 403 if you do not have settings permission

Retrieve a single goal

GET /api/v5/orgs/<organization_id>/goals/<goal_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
  • 403 if you do not have settings permission
  • 404 if goal was not found

Update a goal

You may update goals for your organization. Fields name, allowed_any_room, allowed_rooms or conditions can be updated.

PUT /api/v5/orgs/<organization_id>/goals/<goal_id>

PATCH /api/v5/orgs/<organization_id>/goals/<goal_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
  • 403 if you do not have settings permission
  • 404 if goal was not found

Goal Match API

This API was renamed. See External Goal Match API below.

External Goal Match API

You can use this endpoint to create goal matches from events that happen outside of the webpage where giosg is installed.

When this API should be used

This endpoint should only be used for tracking offline goals. The offline tracking workflow is explained here.

If you want to track goals while the visitor is on the webpage you can use Javascript SDK's Goal Match API

Post new external goal match

1
2
3
4
5
6
7
8
9
{
  "visitor_identity": "customer-12345678",
  "goal_matched_at": "2016-10-10T22:00:49.123Z",
  "goal_value": "123.45",
  "rooms": [
    "ac83d426-be80-4d75-8c62-49a77f98468h",
    "ac83d426-be80-4d75-8c62-49a77f98468g"
  ]
}

POST /api/v5/orgs/<organization_id>/goals/<goal_id>/matches

The external goal matching requires the following attributes.

Attribute Type Editable Description
visitor_identity string required Identifier for the visitor. This must be submitted beforehand using Visitor Identifier API
goal_matched_at datetime required The timestamp for the goal. It is used to link the goal with the visitor's session.
rooms array of UUID's required An array of room uuid's where the goal matched.
goal_value decimal optional Value for this goal event. If not given then the default value for the Goal is used. If there is no default value, the value is left empty.

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 goal was not found
  • 404 if no session is found for 'visitor_identity'.
  • 404 if there is no connected rooms found for visitor session.

Linking the goal to correct visitor session

The selected session is the most recent session for the given visitor_identity, that happened before the goal_matched_at.

When the correct session for the given visitor_identity is found.