REST API

The Da Vinci Signal API exposes a set of core resources that let you create a variety of events in a RESTful manner. All requests require authentication.

Browsing

A set of resources and events related to the general browsing of a website. Many of these form the foundation for triggering more complex events.

Browser

A browser represents a unique web browser on your website. This would be created the first time a user visits. A browser may or may not span multiple unique sessions. Browsers are used by Da Vinci to relate groups of session events together over a long period of time.

POST https://track.coherentpath.com/v1/websites/browsers

Browser parameters

Name	Type	Description
*`user_agent`	String	The user agent of the web browser.
*`language`	String	The language of the web browser.

* If a user_agent or language is not provided - their values will be taken from request headers.

Request example

{
  "browser": {
    "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36",
    "language": "en-US"
  }
}

Response example

{
  "browser": {
    "id": "68fd79a2-b414-4c04-9554-76ea150011ee",
    "created_at": 1614029380,
    "expires_at": 1616621380,
    "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36",
    "language": "en-US"
  }
}

Session

A session represents a timeboxed visit on your website. This would be created anytime a user visits assuming their last session has expired. Sessions are used by Da Vinci to relate a set of events together over a short period of time.

POST https://track.coherentpath.com/v1/websites/sessions

Session parameters

Name	Type	Description
`browser_id`	String	A unique identifier of the web browser.
*`remote_ip`	String	An IP address of the session.

* If a remote_ip is not provided - the IP of the requester will be used.

Request example

{
  "session": {
    "browser_id": "20343c80-722d-4bb5-b67d-e5d8f1dfe523",
    "remote_ip": "192.158.1.38"
  }
}

Response example

{
  "session": {
    "id": "be6c9e1f-fcf0-494d-8ee7-5ea629db78ad",
    "browser_id": "20343c80-722d-4bb5-b67d-e5d8f1dfe523",
    "created_at": 1614029380,
    "expires_at": 1614030280,
    "remote_ip": "192.158.1.38"
  }
}

Identity

An identity represents a known user visiting your website. An identity can be created for a Da Vinci contact or a previous customer. A user performing an event such as login or registration can also create an identity. Identities are used by Da Vinci to relate a set of known user events together over a short period of time.

POST https://track.coherentpath.com/v1/websites/identities

Identity parameters

Name	Type	Description
`browser_id`	String	A unique identifier of the web browser.
`session_id`	String	A unique identifier of the session.
*`contact_id`	String	A unique identifier of Da Vinci contact.
*`email_address`	String	An email address of the user.
`source`	String	The way in which the identification occurred.
`tags`	Array<String>	Additional list of attributes that can be assigned to the identity.
`attributes`	Object	Additional key-value attributes that can be assigned to the identity.

* One of contact_idor email_address must be provided when creating an identity.

Request example

{
  "identity": {
    "browser_id": "df8e2d68-b6db-47eb-9650-37b672797ec1",
    "session_id": "a5b2c77d-9328-4550-8fa4-ad049a690c51",
    "source": "login",
    "tags": ["identity-tag1", "identity-tag2"],
    "attributes": {
      "identity-key1": "identity-value1",
      "identity-key2": "identity-value2"
    }
  }
}

Response example

{
  "identity": {
    "id": "e18009cf-c346-4143-9ce8-6d233a765030",
    "browser_id": "df8e2d68-b6db-47eb-9650-37b672797ec1",
    "session_id": "a5b2c77d-9328-4550-8fa4-ad049a690c51",
    "created_at": 1614029380,
    "contact_id": null,
    "email": null,
    "source": "login",
    "tags": ["identity-tag1", "identity-tag2"],
    "attributes": {
      "identity-key1": "identity-value1",
      "identity-key2": "identity-value2"
    }
  }
}

Page View

A page view represents a single page visit on your website. Page views are used by Da Vinci to provide insight into the navigation and interests of known as well as unknown users.

POST https://track.coherentpath.com/v1/websites/page_views

Page View Parameters

Name	Type	Description
`browser_id`	String	A unique identifier of the web browser.
`session_id`	String	A unique identifier of the session.
`url`	String	The full url of the page visited.
`title`	String	The title of the page visited.
`identity_id`	String	A unique identifier of a known user.
`referrer`	String	The referrer url of the page visited.
`source`	String	The source of the user arrival.
`tags`	Array<String>	Additional list of attributes that can be assigned to the page view.
`attributes`	Object	Additional key-value attributes that can be assigned to the page view.

Request example

{
  "page_view": {
    "browser_id": "cafd51b1-2adb-4d18-9f80-713c7f5efccf",
    "session_id": "140ec1f2-5839-4cf8-95dd-20170b7390fd",
    "url": "https://myshop.com/blog",
    "title": "Blog",
    "tags": ["page-view-tag1", "page-view-tag2"],
    "attributes": {
      "page-view-key1": "page-view-value1",
      "page-view-key2": "page-view-value2"
    }
  }
}

Response example

{
  "page_view": {
    "id": "5824b626-a941-4782-9124-f79fbfab8393",
    "browser_id": "cafd51b1-2adb-4d18-9f80-713c7f5efccf",
    "session_id": "140ec1f2-5839-4cf8-95dd-20170b7390fd",
    "identity_id": null,
    "created_at": 1614029380,
    "url": "https://myshop.com/blog",
    "title": "Blog",
    "tags": ["page-view-tag1", "page-view-tag2"],
    "attributes": {
      "page-view-key1": "page-view-value1",
      "page-view-key2": "page-view-value2"
    }
  }
}

Products

A set of resources and events related to products on a website.

Product

A product represents an individual item or service for sale in the store.

Product parameters

Name	Type	Description
`name`	String	The name of the product.
`variants`	Array<Variant>	A list of variants associated with the product.
`tags`	Array<String>	Additional list of attributes that can be assigned to the product.
`attributes`	Object	Additional key-value attributes that can be assigned to the product.

Product variant parameters

Name	Type	Description
`name`	String	The name of the product variant.
`price`	Money	The price of the product variant.
`tags`	Array<String>	Additional list of attributes that can be assigned to the product.
`attributes`	Object	Additional key-value attributes that can be assigned to the product.

Product page view

A product page view represents a single page visit on your website for a specific product. Product page views are used by Da Vinci to provide deeper insight into the specific interests of known as well as unknown users.

POST https://track.coherentpath.com/v1/products/page_views

Product page view parameters

Name	Type	Description
`browser_id`	String	A unique identifier of the web browser.
`session_id`	String	A unique identifier of the session.
`url`	String	The full url of the product page visited.
`title`	String	The title of the product page visited.
`product`	Product	Information about the product.
`identity_id`	String	A unique identifier of a known user.
`referrer`	String	The referrer url of the product page visited.
`source`	String	The source of the user arrival.
`tags`	Array<String>	Additional list of attributes that can be assigned to the product view.
`attributes`	Object	Additional key-value attributes that can be assigned to the product view.

Request example

{
  "page_view": {
    "browser_id": "f1c89cc9-228f-42bc-a203-0c84dce5ddab",
    "session_id": "ae5f5797-d010-4f36-bbf8-9b9ab5997f8b",
    "url": "https://myshop.com/product",
    "title": "Product",
    "product": {
      "name": "T-Shirt",
      "variants": [
        {           "name": "White",
          "price": {
            "amount": 1000,
            "currency": "USD"
          }
        }
      ]
    },
    "tags": ["page-view-tag1", "page-view-tag2"],
    "attributes": {
      "page-view-key1": "page-view-value1",
      "page-view-key2": "page-view-value2"
    }
  }
}

Response example

{
  "page_view": {
    "id": "1c83eb01-34b9-4e25-bc94-e7d939b8d321",
    "browser_id": "f1c89cc9-228f-42bc-a203-0c84dce5ddab",
    "session_id": "ae5f5797-d010-4f36-bbf8-9b9ab5997f8b",
    "identity_id": null,
    "created_at": 1614029380,
    "url": "https://myshop.com/product",
    "title": "Product",
    "referrer": null,
    "source": null,
    "product": {
      "name": "Sweatshirt",
      "variants": [
        {
          "name": "White",
          "price": {
            "amount": 1000,
            "currency": "USD"
          },
          "tags": [],
          "attributes": {}
        }
      ]
    },
    "tags": ["page-view-tag1", "page-view-tag2"],
    "attributes": {
      "page-view-key1": "page-view-value1",
      "page-view-key2": "page-view-value2"
    }
  }
}

Product search

A product search represents a single search on your website using a specific query. Product searches are used by Da Vinci to provide deeper insight into the specific interests of known as well as unknown users.

POST https://track.coherentpath.com/v1/products/searches

Product search parameters

Name	Type	Description
`browser_id`	String	A unique identifier of the web browser.
`session_id`	String	A unique identifier of the session.
`query`	String	The search query term used.
`identity_id`	String	A unique identifier of a known user.
`products`	ArrayProduct	A list of products returned by the search. This can be limited to a subset of the total list.
`tags`	Array<String>	Additional list of attributes that can be assigned to the search.
`attributes`	Object	Additional key-value attributes that can be assigned to the search.

Request example

{
  "search": {
    "browser_id": "aadd0167-7b4b-4e94-a081-5272f4b6b407",
    "session_id": "dcfd9ff6-7fab-4956-858a-52a57cfc534e",
    "identity_id": "6e2fd87b-2383-46bb-a67e-1b4c0d2a0d2a",
    "query": "t shirts",
    "tags": ["search-tag1", "search-tag2"],
    "attributes": {
      "search-key1": "search-value1",
      "search-key2": "search-value2"
    },
    "products": [
      {
        "name": "Men's T-Shirt"
      },
      {
        "name": "Women's T-Shirt"
      }
    ]
  }
}

Response example

{
  "search": {
    "id": "c6bf5cad-63a0-418d-9c7b-d5b8d3db73b3",
    "browser_id": "aadd0167-7b4b-4e94-a081-5272f4b6b407",
    "session_id": "dcfd9ff6-7fab-4956-858a-52a57cfc534e",
    "identity_id": "6e2fd87b-2383-46bb-a67e-1b4c0d2a0d2a",
    "query": "t shirts",
    "created_at": 1614029380,
    "tags": ["search-tag1", "search-tag2"],
    "attributes": {
      "search-key1": "search-value1",
      "search-key2": "search-value2"
    },
    "products": [
      {
        "name": "Men's T-Shirt",
        "variants": [],
        "tags": [],
        "attributes": {}
      },
      {
        "name": "Women's T-Shirt",
        "variants": [],
        "tags": [],
        "attributes": {}
      }
    ]
  }
}

Orders

Order

An order is a customer's completed request to purchase one or more products from a shop.

Order parameters

Name	Type	Description
`tags`	Array<String>	Additional list of attributes that can be assigned to the order.
`attributes`	Object	Additional key-value attributes that can be assigned to the order.
`processed_at`	Integer	The timestamp when the order was processed by an ecommerce system.
`discount`	Money	The sum of all discounts.
`subtotal`	Money	The sum of all line item product prices after discounts but before shipping, and taxes.
`items`	Array<Order Item>	A list of line items associated with the order.

Order item parameters

Name	Type	Description
`tags`	Array<String>	Additional list of attributes that can be assigned to the line item.
`attributes`	Object	Additional key-value attributes that can be assigned to the line item.
`name`	String	The name of the product variant.
`quantity`	Integer	The total number of items.
`discount`	Money	The sum of all discounts applied to the line item.
`price`	Money	The price of the product variant.

Order completion

An order completion is an event created at the final step of an order. It should represent the final transaction - once all previous steps are completed.

POST https://track.coherentpath.com/v1/orders/completions

Order completion parameters

Name	Type	Description
`browser_id`	String	A unique identifier of the web browser.
`session_id`	String	A unique identifier of the session.
`identity_id`	String	A unique identifier of a known user.
`order`	Order	Detailed information about the order.
`tags`	Array<String>	Additional list of attributes that can be assigned to the order completion.
`attributes`	Object	Additional key-value attributes that can be assigned to the order completion.

Request example

{
  "completion": {
    "browser_id": "e56c9d3a-505d-4245-8809-150941a12970",
    "session_id": "624070e1-a694-4e67-a550-087795ab55d8",
    "identity_id": "0e0ce0ce-058d-44d8-b811-1b6d5f6794d2",
    "order": {
      "source": "web",
      "tags": ["order-tag1", "order-tag2"],
      "attributes": {
        "order-key1": "order-value1",
        "order-key2": "order-value2"
      },
      "processed_at": 1614029375,
      "discount": {
        "amount": 100,
        "currency": "USD"
      },
      "subtotal": {
        "amount": 1000,
        "currency": "USD"
      },
      "items": [
        {
          "tags": ["product-tag1", "product-tag2"],
          "attributes": {
            "product-key1": "product-value1",
            "product-key2": "product-value2"
          },
          "quantity": 1,
          "discount": {
            "amount": 100,
            "currency": "USD"
          },
          "price": {
            "amount": 1000,
            "currency": "USD"
          }
        }
      ]
    }
  }
}

Response example

{
  "completion": {
    "id": "2977a200-b749-483a-a91e-a9ce71939eae",
    "browser_id": "e56c9d3a-505d-4245-8809-150941a12970",
    "session_id": "624070e1-a694-4e67-a550-087795ab55d8",
    "identity_id": "0e0ce0ce-058d-44d8-b811-1b6d5f6794d2",
    "created_at": 1614029380,
    "tags": [],
    "attributes": {},
    "order": {
      "source": "web",
      "tags": ["order-tag1", "order-tag2"],
      "attributes": {
        "order-key1": "order-value1",
        "order-key2": "order-value2"
      },
      "processed_at": 1614029375,
      "discount": {
        "amount": 100,
        "currency": "USD"
      },
      "subtotal": {
        "amount": 1000,
        "currency": "USD"
      },
      "items": [
        {
          "tags": ["product-tag1", "product-tag2"],
          "attributes": {
            "product-key1": "product-value1",
            "product-key2": "product-value2"
          },
          "quantity": 1,
          "discount": {
            "amount": 100,
            "currency": "USD"
          },
          "price": {
            "amount": 1000,
            "currency": "USD"
          }
        }
      ]
    }
  }
}

Order cancelation

An order cancelation is an event created whenever a user chooses to cancel an existing order. A cancelation should only be triggered before the order has shipped. A full representation of the existing order should be included in the request if possible.

POST https://track.coherentpath.com/v1/orders/cancelations

Order cancelation parameters

Name	Type	Description
`browser_id`	String	A unique identifier of the web browser.
`session_id`	String	A unique identifier of the session.
`identity_id`	String	A unique identifier of a known user.
`order`	Order	Detailed information about the order.
`tags`	Array<String>	Additional list of attributes that can be assigned to the order completion.
`attributes`	Object	Additional key-value attributes that can be assigned to the order completion.

Request example

{
  "cancelation": {
    "browser_id": "c6a29bec-5a53-4736-b892-8641373b0d52",
    "session_id": "dce206f0-99f2-4f04-b3e1-b90ba3bc2f08",
    "identity_id": "e4557154-34be-4c05-aefa-fb5afaae3a02",
    "order": {
      "source": "web",
      "tags": ["order-tag1", "order-tag2"],
      "attributes": {
        "order-key1": "order-value1",
        "order-key2": "order-value2"
      },
      "processed_at": 1614029375,
      "discount": {
        "amount": 100,
        "currency": "USD"
      },
      "subtotal": {
        "amount": 1000,
        "currency": "USD"
      },
      "items": [
        {
          "tags": ["product-tag1", "product-tag2"],
          "attributes": {
            "product-key1": "product-value1",
            "product-key2": "product-value2"
          },
          "quantity": 1,
          "discount": {
            "amount": 100,
            "currency": "USD"
          },
          "price": {
            "amount": 1000,
            "currency": "USD"
          }
        }
      ]
    }
  }
}

Response example

{
  "cancelation": {
    "id": "ece22bc7-2267-4e2e-9d78-12fa34b9f3ed",
    "browser_id": "c6a29bec-5a53-4736-b892-8641373b0d52",
    "session_id": "dce206f0-99f2-4f04-b3e1-b90ba3bc2f08",
    "identity_id": "e4557154-34be-4c05-aefa-fb5afaae3a02",
    "created_at": 1614029380,
    "tags": [],
    "attributes": {},
    "order": {
      "source": "web",
      "tags": ["order-tag1", "order-tag2"],
      "attributes": {
        "order-key1": "order-value1",
        "order-key2": "order-value2"
      },
      "processed_at": 1614029375,
      "discount": {
        "amount": 100,
        "currency": "USD"
      },
      "subtotal": {
        "amount": 1000,
        "currency": "USD"
      },
      "items": [
        {
          "tags": ["product-tag1", "product-tag2"],
          "attributes": {
            "product-key1": "product-value1",
            "product-key2": "product-value2"
          },
          "quantity": 1,
          "discount": {
            "amount": 100,
            "currency": "USD"
          },
          "price": {
            "amount": 1000,
            "currency": "USD"
          }
        }
      ]
    }
  }
}

Order refund

An order refund is an event created whenever a user receives a refund for an existing order. A refund should only be triggered after the order has shipped. A full representation of the existing order should be included in the request if possible.

POST https://track.coherentpath.com/v1/orders/refunds

Order refund parameters

Name	Type	Description
`browser_id`	String	A unique identifier of the web browser.
`session_id`	String	A unique identifier of the session.
`identity_id`	String	A unique identifier of a known user.
`order`	Order	Detailed information about the order.
`tags`	Array<String>	Additional list of attributes that can be assigned to the order completion.
`attributes`	Object	Additional key-value attributes that can be assigned to the order completion.

Request example

{
  "refund": {
    "browser_id": "386836c1-4b77-4d59-99cb-8cd3e3a894d3",
    "session_id": "24615e38-b8e1-4524-a6f5-79a86368ca26",
    "identity_id": "3ededc74-99de-40ac-95c5-6587a8771f6d",
    "order": {
      "source": "web",
      "tags": ["order-tag1", "order-tag2"],
      "attributes": {
        "order-key1": "order-value1",
        "order-key2": "order-value2"
      },
      "processed_at": 1614029375,
      "discount": {
        "amount": 100,
        "currency": "USD"
      },
      "subtotal": {
        "amount": 1000,
        "currency": "USD"
      },
      "items": [
        {
          "tags": ["product-tag1", "product-tag2"],
          "attributes": {
            "product-key1": "product-value1",
            "product-key2": "product-value2"
          },
          "quantity": 1,
          "discount": {
            "amount": 100,
            "currency": "USD"
          },
          "price": {
            "amount": 1000,
            "currency": "USD"
          }
        }
      ]
    }
  }
}

Response example

{
  "refund": {
    "id": "d12814d2-0310-40a3-812a-a7760309c3bd",
    "browser_id": "386836c1-4b77-4d59-99cb-8cd3e3a894d3",
    "session_id": "24615e38-b8e1-4524-a6f5-79a86368ca26",
    "identity_id": "3ededc74-99de-40ac-95c5-6587a8771f6d",
    "created_at": 1614029380,
    "tags": [],
    "attributes": {},
    "order": {
      "source": "web",
      "tags": ["order-tag1", "order-tag2"],
      "attributes": {
        "order-key1": "order-value1",
        "order-key2": "order-value2"
      },
      "processed_at": 1614029375,
      "discount": {
        "amount": 100,
        "currency": "USD"
      },
      "subtotal": {
        "amount": 1000,
        "currency": "USD"
      },
      "items": [
        {
          "tags": ["product-tag1", "product-tag2"],
          "attributes": {
            "product-key1": "product-value1",
            "product-key2": "product-value2"
          },
          "quantity": 1,
          "discount": {
            "amount": 100,
            "currency": "USD"
          },
          "price": {
            "amount": 1000,
            "currency": "USD"
          }
        }
      ]
    }
  }
}

Money

Money is represented as it own object when used in things like orders and products.

Money parameters

Name	Type	Description
`amount`	Integer	A positive integer representing a monetary value (e.g., `100` represents $1.00)
`currency`	String	The currency of the money amount.

console.log('It works!')

REST API

Browsing

Browser

Browser parameters

Request example

Response example

Session

Session parameters

Request example

Response example

Identity

Identity parameters

Request example

Response example

Page View

Page View Parameters

Request example

Response example

Products

Product

Product parameters

Product variant parameters

Product page view

Product page view parameters

Request example

Response example

Product search

Product search parameters

Request example

Response example

Orders

Order

Order parameters

Order item parameters

Order completion

Order completion parameters

Request example

Response example

Order cancelation

Order cancelation parameters

Request example

Response example

Order refund

Order refund parameters

Request example

Response example

Money

Money parameters

Categories