Contact Log in

Customer Relationship Management API

The Customer Relationship Management (CRM) API allows for full control over your object types and object data. There are three main sections of the API. Object Types, which handle the schema, format, and retention period for the data. Object Versions which track the changes to your Object Types. Objects which act as containers for the data you wish to store.

Terminology

To make a distinction between user defined objects and standard objects, the former are referred to as CRM objects and the latter JSON objects. If the term object is mentioned without any signifier, we are referring to CRM objects.

Endpoints

Object Types

Object Types define the structure and schema for objects within the CRM. To define an object type, you must define a schema which follows this format:

{
  "type": "object",
  "props": {
    ...
  }
}

Where props can be defined as other objects or data types, such as string, number, bool and the fields can be set to allow null or array values. The example below demonstrates a schema using all these types and properties.

{
  "type": "object",
  "props": {
    "customerName": {
      "type": "string"
    },
    "customerID": {
      "type": "string"
    },
    "totalSpent": {
      "type": "number",
      "null": true
    },
    "products": {
      "type": "object",
      "props": {
        "name": {
          "type": "string"
        },
        "isSubscription": {
          "type": "bool",
          "null": true
        },
        "price": {
          "type": "number"
        },
        "quantity": {
          "type": "number"
        }
      },
      "array": true,
      "null": true
    }
  }
}

The resulting object would look as such:

{
  "customerName": "Bob Smith",
  "customerID": "C1027",
  "totalSpent": 100.97,
  "products": [
    {
      "name": "Broiler Pro Smart Grill",
      "price": 59.97,
      "quantity": 1
    },
    {
      "name":"Broiler Pro Clean Fuel",
      "price": 39.00,
      "quantity": 1,
      "isSubscription": true
    },
    {
      "name":"Broiler Pro Cleaning Pads",
      "price": 1.00,
      "quantity": 2,
      "isSubscription": false
    }
  ]
}

POST Object Types

POST https://dashboard.thankful.ai/api/v1/object-types

Create a new object type with a given schema.

Request Body

Parameter	Description	Type	Required
retainDays	The duration you wish to keep each object in the CRM.	int	Yes
name	The name of your object type.	string	Yes
schemaData	The updated valid schema of the object type. Reference the section Object Types to see a valid schema.	JSON Schema	Yes

Example Request Body

{
  "retainDays": 10,
  "name": "productHistory",
  "schemaData": {
    "type": "object",
    "props": {
      "customerName": {
        "type": "string"
      },
      "customerID": {
        "type": "string"
      },
      "totalSpent": {
        "type": "number",
        "null": true
      },
      "products": {
        "type": "object",
        "props": {
          "name": {
            "type": "string"
          },
          "isSubscription": {
            "type": "bool",
            "null": true
          },
          "price": {
            "type": "number"
          },
          "quantity": {
            "type": "number"
          }
        },
        "array": true,
        "null": true
      }
    }
  }
}

Response Body

Field	Description	Type
id	The ID of the object type.	int
retainDays	How long object data is retained in the CRM.	int
name	The name of the object type.	string
schemaData	The schema for the object type.	JSON Schema
createdAt	The UTC timestamp for when the object type was created.	RFC 3339 Timestamp

Example Response

{
  "objectType": {
    "id": 7,
    "name": "productHistory",
    "schemaData": {
      "type": "object",
      "props": {
        "customerName": {
          "type": "string"
        },
        "customerID": {
          "type": "string"
        },
        "totalSpent": {
          "type": "number",
          "null": true
        },
        "products": {
          "type": "object",
          "props": {
            "name": {
              "type": "string"
            },
            "isSubscription": {
              "type": "bool",
              "null": true
            },
            "price": {
              "type": "number"
            },
            "quantity": {
              "type": "number"
            }
          },
          "array": true,
          "null": true
        }
      }
    },
    "retainDays": 10,
    "createdAt": "2021-01-01T00:00:00Z"
  }
}

GET Object Types

GET https://dashboard.thankful.ai/api/v1/object-types

Get the list of object types defined in your CRM.

Request Query

Parameter	Description	Example
by	Sort by the following fields: `id` `name`	`by=name`
desc	Sort by descending order. Defaults to false.	`desc=true`
limit	Max results returned per request. Defaults to 25. Maximum is 100.	`limit=50`
offset	Page offset for the results.	`offset=25`

Response Body

Field	Description	Type
objectTypes	An array of CRM object types.	array

Example Response

{
  "objectTypes": [
    {
      "id": 7,
      "name": "productHistory",
      "schemaData": {
        "type": "object",
        "props": {
          "products": {
            "null": true,
            "type": "object",
            "array": true,
            "props": {
              "name": {
                "type": "string"
              },
              "price": {
                "type": "number"
              },
              "quantity": {
                "type": "number"
              },
              "isSubscription": {
                "null": true,
                "type": "bool"
              }
            }
          },
          "customerID": {
            "type": "string"
          },
          "totalSpent": {
            "null": true,
            "type": "number"
          },
          "customerName": {
            "type": "string"
          }
        }
      },
      "retainDays": 10,
      "version": 1,
      "createdAt": "2021-01-1T00:00:00"
    }
  ]
}

GET Object Type

GET https://dashboard.thankful.ai/api/v1/object-types/:typeID

Get a specific object type with the given type ID. Returns the most current version.

Request Path

Parameter	Description	Type
typeID	The ID of the object type you wish to retrieve.	int

Response Body

Field	Description	Type
id	The ID of the object type.	int
retainDays	How long object data is retained in the CRM.	int
name	The name of the object type.	string
schemaData	The schema for the most current version of the object type.	JSON Schema
createdAt	The UTC timestamp for when the object type was created.	RFC 3339 Timestamp
version	The version number of the object type.	int

Example Response

{
  "objectType": {
    "id": 7,
    "name": "productHistory",
    "schemaData": {
      "type": "object",
      "props": {
        "customerName": {
          "type": "string"
        },
        "customerID": {
          "type": "string"
        },
        "totalSpent": {
          "type": "number",
          "null": true
        },
        "products": {
          "type": "object",
          "props": {
            "name": {
              "type": "string"
            },
            "isSubscription": {
              "type": "bool",
              "null": true
            },
            "price": {
              "type": "number"
            },
            "quantity": {
              "type": "number"
            }
          },
          "array": true,
          "null": true
        }
      }
    },
    "retainDays": 10,
    "createdAt": "2021-01-01T00:00:00Z"
  }
}

PUT Object Type

PUT https://dashboard.thankful.ai/api/v1/object-types/:typeID

Update an object type with the specified type ID. This will increment the version number on an object type.

Request Path

Parameter	Description	Type
typeID	The ID of the object type you wish to modify.	int

Request Body

Parameter	Description	Type	Required
retainDays	The duration you wish to keep each object in the CRM.	int	Yes
name	The name of your object type.	string	Yes
schemaData	The updated valid schema of the object type. Reference the section Object Types to see a valid schema.	JSON Schema	Yes

Example Request Body

{
  "retainDays": 90,
  "name": "productHistory",
  "schemaData": {
    "type": "object",
    "props": {
      "customerName": {
        "type": "string"
      },
      "customerID": {
        "type": "string"
      },
      "totalSpent": {
        "type": "number",
        "null": true
      },
      "isVIP": {
        "type": "bool",
        "null": true
      },
      "products": {
        "type": "object",
        "props": {
          "name": {
            "type": "string"
          },
          "isSubscription": {
            "type": "bool",
            "null": true
          },
          "price": {
            "type": "number"
          },
          "quantity": {
            "type": "number"
          }
        },
        "array": true,
        "null": true
      }
    }
  }
}

Example Response

200 OK

DELETE Object Type

DELETE https://dashboard.thankful.ai/api/v1/object-types/:typeID

Delete a given object type with the given type ID and all associated objects.

Request Path

Parameter	Description	Type
typeID	The ID of the object type you wish to delete.	int

Example Response

200 OK

Object Versions

Each object type has an associated version, beginning at version 1 when the object type is first created. Any updates to the object type schema or its retention period will increment the version number.

GET Object Versions

GET https://dashboard.thankful.ai/api/v1/object-types/:typeID/versions

Get all the versions for an object type with the specified type ID.

Request Path

Parameter	Description	Type
typeID	The ID of the object type for which you want the versions.	int

Request Query

Parameter	Description	Example
by	Sort by the following fields: `id` `name`	`by=name`
desc	Sort by descending order. Defaults to false.	`desc=true`
limit	Max results returned per request. Defaults to 25. Maximum is 100.	`limit=50`
offset	Page offset for the results.	`offset=25`

Response Body

Field	Description	Type
versions	An array of CRM object types.	array

Example Response

{
  "versions": [
    {
      "id": 7,
      "name": "productHistory",
      "schemaData": {
        "type": "object",
        "props": {
          "products": {
            "null": true,
            "type": "object",
            "array": true,
            "props": {
              "name": {
                "type": "string"
              },
              "price": {
                "type": "number"
              },
              "quantity": {
                "type": "number"
              },
              "isSubscription": {
                "null": true,
                "type": "bool"
              }
            }
          },
          "customerID": {
            "type": "string"
          },
          "totalSpent": {
            "null": true,
            "type": "number"
          },
          "customerName": {
            "type": "string"
          }
        }
      },
      "retainDays": 90,
      "version": 1,
      "createdAt": "2021-06-17T00:00:00"
    },
    {
      "id": 7,
      "name": "productHistory",
      "schemaData": {
        "type": "object",
        "props": {
          "isVIP": {
            "null": true,
            "type": "bool"
          },
          "products": {
            "null": true,
            "type": "object",
            "array": true,
            "props": {
              "name": {
                "type": "string"
              },
              "price": {
                "type": "number"
              },
              "quantity": {
                "type": "number"
              },
              "isSubscription": {
                "null": true,
                "type": "bool"
              }
            }
          },
          "customerID": {
            "type": "string"
          },
          "totalSpent": {
            "null": true,
            "type": "number"
          },
          "customerName": {
            "type": "string"
          }
        }
      },
      "retainDays": 90,
      "version": 2,
      "createdAt": "2021-07-01T00:00:00"
    }
  ]
}

GET Object Version

GET https://dashboard.thankful.ai/api/v1/object-types/:typeID/versions/:version

Get a specific version of an object type specified by its version number and type ID respectively.

Request Path

Parameter	Description	Type
typeID	The ID of the object type.	int
version	The version of the object type you wish to retrieve.	int

Response Body

Field	Description	Type
version	The requested version of the CRM object type.	CRM Object Type

Example Response

{
    "version": {
        "id": 7,
        "name": "productHistory",
        "schemaData": {
            "type": "object",
            "props": {
                "products": {
                    "null": true,
                    "type": "object",
                    "array": true,
                    "props": {
                        "name": {
                            "type": "string"
                        },
                        "price": {
                            "type": "number"
                        },
                        "quantity": {
                            "type": "number"
                        },
                        "isSubscription": {
                            "null": true,
                            "type": "bool"
                        }
                    }
                },
                "customerID": {
                    "type": "string"
                },
                "totalSpent": {
                    "null": true,
                    "type": "number"
                },
                "customerName": {
                    "type": "string"
                }
            }
        },
        "retainDays": 90,
        "version": 1,
        "createdAt": "2021-06-17T00:00:00"
    }
}

Objects

Objects are the data you wish to store in the CRM following the schema for the object type. In order to create an object, you must first create an object type. Objects are associated with particular versions of an object type, which will be indicated when you retrieve an object from the CRM. Objects are retained for the period specified on its version of the object type.

POST Objects

POST https://dashboard.thankful.ai/api/v1/object-types/:typeID/objects

Create an object of the given object type specified by the type ID in the path.

Request Path

Parameter	Description	Type
typeID	The ID of the object type.	int

Request Body

The object following the object type schema.

Example Request Body

{
    "customerName": "Bob Smith",
    "customerID": "C1027",
    "totalSpent": 100.97,
    "products": [
        {
            "name": "Broiler Pro Smart Grill",
            "price": 59.97,
            "quantity": 1
        },
        {
            "name":"Broiler Pro Clean Fuel",
            "price": 39.00,
            "quantity": 1,
            "isSubscription": true
        },
        {
            "name":"Broiler Pro Cleaning Pads",
            "price": 1.00,
            "quantity": 2,
            "isSubscription": false
        }
    ]
}

Response Body

Field	Description	Type
object	Contains object data and metadata.	JSON Object
id	The ID of the object.	int
objectTypeID	The ID of the object type.	int
version	The version of the object type.	int
byteSize	The size of the object in bytes.	int
createdAt	The UTC timestamp for when the object was created.	RFC 3339 Timestamp
data	Contains the CRM object as defined by the object type’s schema.	CRM Object

Example Response

{
  "object": {
    "id": 14,
    "objectTypeID": 7,
    "data": {
      "products": [
        {
          "name": "Broiler Pro Smart Grill",
          "price": 59.97,
          "quantity": 1
        },
        {
          "name": "Broiler Pro Clean Fuel",
          "price": 39,
          "quantity": 1,
          "isSubscription": true
        },
        {
          "name": "Broiler Pro Cleaning Pads",
          "price": 1,
          "quantity": 2,
          "isSubscription": false
        }
      ],
      "customerID": "C1027",
      "totalSpent": 100.97,
      "customerName": "Bob Smith"
    },
    "createdAt": "2021-06-17T00:00:00",
    "version": 1,
    "byteSize": 341
  }
}

GET Objects

GET https://dashboard.thankful.ai/api/v1/object-types/:typeID/objects

Get all objects of a given type specified by the type ID or all objects of a given type specified by the URL encoded query q.

Request Path

Parameter	Description	Type
typeID	The ID of the object type.	int

Request Query

Parameter	Description	Example
q	Search Query allows you to search objects by their field values defined in the schema. Queries must be URL encoded. The pattern is `data.fieldName`.	`q=data.customerID`
by	Sort by the following fields: `id` `byteSize`	`by=byteSize`
desc	Sort by descending order. Defaults to false.	`desc=true`
limit	Max results returned per request. Defaults to 25. Maximum is 100.	`limit=50`
offset	Page offset for the results.	`offset=25`

Response Body

Field	Description	Type
objects	Array of JSON objects containing CRM object data and metadata.	array
id	The ID of the object.	int
objectTypeID	The ID of the object type.	int
version	The version of the object type.	int
byteSize	The size of the object in bytes.	int
createdAt	The UTC timestamp for when the object was created.	RFC 3339 Timestamp
data	Contains the CRM object as defined by the object type’s schema.	CRM Object

Example Response

{
  "objects":[
    {
      "id":14,
      "objectTypeID":7,
      "data":{
        "products":[
          {
            "name":"Broiler Pro Smart Grill",
            "price":59.97,
            "quantity":1
          },
          {
            "name":"Broiler Pro Clean Fuel",
            "price":39.00,
            "quantity":1,
            "isSubscription":true
          },
          {
            "name":"Broiler Pro Cleaning Pads",
            "price":1.00,
            "quantity":2,
            "isSubscription":false
          }
        ],
        "customerID":"C1027",
        "totalSpent":100.97,
        "customerName":"Bob Smith"
      },
      "createdAt":"2021-06-17T00:00:00",
      "version":1,
      "byteSize":341
    }
  ]
}

GET Object

GET https://dashboard.thankful.ai/api/v1/object-types/:typeID/objects/:objectID

Get a specific object of an object type specified by the object ID and type ID respectively.

Request Path

Parameter	Description	Type
typeID	The ID of the object type for the object you wish to retrieve.	int
objectID	The ID of the object you wish to retrieve.	int

Response Body

Field	Description	Type
object	Contains object data and metadata.	JSON Object
id	The ID of the object.	int
objectTypeID	The ID of the object type.	int
version	The version of the object type.	int
byteSize	The size of the object in bytes.	int
createdAt	The UTC timestamp for when the object was created.	RFC 3339 Timestamp
data	Contains the CRM object as defined by the object type’s schema.	CRM Object

Example Response

{
  "object": {
    "id": 14,
    "objectTypeID": 7,
    "data": {
      "products": [
        {
          "name": "Broiler Pro Smart Grill",
          "price": 59.97,
          "quantity": 1
        },
        {
          "name": "Broiler Pro Clean Fuel",
          "price": 39,
          "quantity": 1,
          "isSubscription": true
        },
        {
          "name": "Broiler Pro Cleaning Pads",
          "price": 1,
          "quantity": 2,
          "isSubscription": false
        }
      ],
      "customerID": "C1027",
      "totalSpent": 100.97,
      "customerName": "Bob Smith"
    },
    "createdAt": "2021-06-17T00:00:00",
    "version": 1,
    "byteSize": 341
  }
}

PUT Object

PUT https://dashboard.thankful.ai/api/v1/object-types/:typeID/objects/:objectID

Update the specified object of a given type with their respective IDs specificed in the path parameters. The request body is the object with the applied updates.

Request Path

Parameter	Description	Type
typeID	The ID of the object type for the object you wish to update.	int
objectID	The ID of the object you wish to update.	int

Request Body

The object following the object type schema.

Example Request Body

{
  "customerName": "Bob Smith",
  "customerID": "C1027",
  "totalSpent": 117.97,
  "products": [
    {
      "name": "Broiler Pro Smart Grill",
      "price": 59.97,
      "quantity": 1
    },
    {
      "name":"Broiler Pro Clean Fuel",
      "price": 39.00,
      "quantity": 1,
      "isSubscription": true
    },
    {
      "name":"Broiler Pro Cleaning Pads",
      "price": 1.00,
      "quantity": 2,
      "isSubscription": false
    },
    {
      "name":"Broiler Pro 2 Year Warranty",
      "price": 17.00,
      "quantity": 1
    }
  ]
}

Example Response

200 OK

DELETE Object

DELETE https://dashboard.thankful.ai/api/v1/object-types/:typeID/objects/:objectID

Delete a specific object of a particular object type as specified by their respective object and type IDs.

Request Path

Parameter	Description	Type
typeID	The ID of the object type for the object you wish to delete.	int
objectID	The ID of the object you wish to delete.	int

Example Response

200 OK

Ask Support