POST
api
/
v1
/
identify
await fetch('https://functionary.run/api/v1/identify', 
    {  
        method: "POST", 
        header: {
            Authorization: "Bearer MY-TOKEN"
        }
        body: {
            ids: ['10', '[email protected]'],
            model: 'customer',
        } 
    }
)

{
  "statusCode": 200
}

​
Basics

There are 2 main API endpoints for functionary. The first is /api/v1/identify. The second is /api/v1/events.

​
How it works

identify is how you create different instances of models you’ve defined in your config.

Before you can send any events for an object, you need to create it by calling identify.

This endpoint is meant to be fired the multiple time, not just the first time an app learns about an model instance. To update a model instance, you also call identify. For example, you might call identify to create a user. The user has a property task_created. To updated task_created, you’ll call identify with the new value for task_created. identify is last write wins, so update the model as it makes sense.

​
Parameters

displayName
string

Human-readable name of an instance of a model that is identified

This model must exist in you config file. see Models
model
string
required

Model type of the object you are trying to identify.

ids
(string | number)[]
required

id or ids of the object your are trying to create. see below for explination.

childIds
(string | number)[]

The ids of the child objects for this model instance. If ids representing multiple different child objects are sent, the identified model instance will be set to the parent for ALL the different objects. If the childId doesn’t yet exist, the id will be saved and paired when the child model instance is created.

childModel
string

The type of the model being assigned as the child. This is for to avoiding id collisions accross model types. For example, you may send childIds = [1], but it is possible that a model where id=1 exists for both model types of “organization” and “customer”. If childModel="customer" exists functionary knows to only assign the relationship of “child” to “customer” model not the organization. If it doesn’t exist, functionary will assign the relationship to the first model it finds with a matching id.

parentIds
(string | number)[]

The ids of the parent object for this model instance. If ids representing multiple different parent objects are sent, the identified model instance will be set to a child for ALL the different objects. If the parentId doesn’t yet exist, the id will be saved and paired when the parent model instance is created.

parentModel
string

The type of the model being assigned as the parent. This is for to avoiding id collisions accross model types. For example, you may send parentIds = [1], but it is possible that a model where id=1 exists for both model types of “organization” and “customer”. If parentModel="customer" exists functionary knows to only assign the relationship of “parent” to “customer” model not the organization. If it doesn’t exist, functionary will assign the relationship to the first model it finds with a matching id.

properties
object

Properties you want stored on the model instance you are creating.

Authorization
object

Your api key found in the dashboard under settings

​
Aliases and Ids

A model instances can have MANY different ids and are easily updated. To add more ids to model, just send them along with already identified ids.

If there are no existing ids in the ids payload for existing model instances, functionary will create a new model instance.

If an id in the payload already belongs to a model instance, the payload are will be treated as an update for that model.

Properties and displayName will be overwritten with new values. Additional ids will be added to that model.

Ids are unique within the same model type. This means you can have an id = 837 for a customer model instance and an id = 837 for a organization model instance, but you can’t have 2 customer model instances with id = 837.

If two different typed models exist with the same id (noted above), you’ll need to use the optional childModel or the parentModel parameters in the /identify request body to assign relationships. This avoids a relationship being assigned to the wrong model.

For example, if I /identify a “customer” model with ids = [1], assuming there is no customer yet created with that id, a model will be created. Now if I /identify a “customer” model with ids = [1, [email protected]], a new model will NOT be created, instead the original model with ids = [1] will be updated.

After those 2 calls, let’s say I call /identify (or /event) with only ids = [[email protected]], we will be referrencing the same model where ids = [1].

If you think you need a model to share an id, you may want to consider a parent model instead.

ExampleEvents