Universal CRM API - Writing data

Xkit's Universal CRM API allows you to define events to insert or update records in your users' CRM.

Your users determine how these inserts or updates work in the context of their CRM data to complete the integration.

Create data

Rather than creating records directly in the user's CRM, you'll invoke events to allow your users to create the appropriate records.

This is particularly important because CRM record creation frequently involves a large number of required or default fields that your app knows nothing about.

In some cases, your users may even use CRM Link to defer actual object creation to their CRM's native workflow engine.

Here's how handling a create event looks from the user's perspective:

Define create event

To define a create event, you'll pass an object to the events object of your CRM Object's definition in your CRM Link invocation with the following structure:

• Key: this is the slug of the event, which you'll use when invoking the event in the Xkit API
• Value: an object with the following structure
  • type: create
  • name: the user-facing name of the event, e.g. "Create Opportunity"
  • description: the user-facing description of the event and how the user should handle it, e.g. "Create new opportunities for sales documents that do not have one."
  • payloadSchema: Xkit-flavored JSON describing the schema of the payload you'll provide when invoking the event

await linkCRM('example.xkit.co', token, {
  connectionID: 'context-id',
  objects: {
    opportunity: {
      events: {
        create_opportunity: {
          type: "create",
          label: "Create Opportunity",
          description: "Create new opportunities for sales documents that do not have one.",
          payloadSchema: {
            name: {
              type: "string",
              label: "Opportunity Name",
              description: "Desired name of the opportunity"
            }
          }
        }
      }
    }
  }
})

Invoke create event

Invoke the create event by using the Invoke Event endpoint.

If an object was created, it's id and mapped fields will be returned to you. Save the id of the returned CRM record to associate with an object in your database.

Here's an example request and response for invoking a create event for a CRM object with the slug opportunity and an event with the slug create_opportunity:

Request

POST /api/v1/crm/<connectionID>/objects/opportunity/events/create_opportunity_for_document HTTP/1.1
Host: app.xkit.co
Authorization: Basic <credentials>

{
  "payload": {
    "name": "Apple Sales Contract"
  }
}

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "record": {
    "type": "opportunity",
    "id": "Opportunity:09878",
    "data": {
      "document_name": "Oracle Sales Contract",
      "document_tags": {}
    }
  }
}

Update data

Rather than updating data directly in the user's CRM, you'll invoke events to allow your users to update the data in a way that makes sense for their CRM.

Here's how handling an update looks from the user's perspective:

In some cases, your users may even use CRM Link to defer actual updates to their CRM's native workflow engine.

To request the update of an existing CRM record, you'll define and emit an update event in the context of a record previously fetched from the CRM.

Define update event

To define an update event, you'll pass an object to the events object of your CRM Object's definition in your CRM Link invocation with the following structure:

• Key: this is the slug of the event, which you'll use when invoking the event in the Xkit API
• Value: an object with the following structure
  • type: update
  • name: the user-facing name of the event, e.g. "Document Updated"
  • description: the user-facing description of the event and how the user should handle it, e.g. "Occurs when relevant document properties change."
  • payloadSchema: Xkit-flavored JSON describing the schema of the payload you'll provide when invoking the event

await linkCRM('example.xkit.co', token, {
  connectionID: 'context-id',
  objects: {
    opportunity: {
      events: {
        document_updated: {
          type: "update",
          label: "Document Updated",
          description: "Occurs when relevant document properties change.",
          payloadSchema: {
            name: {
              label: "Document Name",
              description: "Updated name of the document",
              type: "string"
            },
            updated_at: {
              label: "Document Last Update Time",
              description: "ISO 8601 Date/Time of the last update made to the document",
              type: "string",
              format: "datetime"
            }
          }
        }
      }
    }
  }
})

Invoke update event

Invoke the update event by using the Invoke Event endpoint.

The updated object will be returned to you with its mapped fields.

Here's an example request and response for invoking a update event for a CRM object with the slug opportunity, the CRM Record Opportunity:09876 and an event with the slug document_updated:

Request

POST /api/v1/crm/<connectionID>/objects/opportunity/Opportunity:09876/events/document_updated HTTP/1.1
Host: app.xkit.co
Authorization: Basic <credentials>

{
  "payload": {
    "name": "Sales Contract",
    "updated_at": "2022-05-17T23:17:53Z"
  }
}

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "record": {
    "type": "opportunity",
    "id": "Opportunity:09876",
    "data": {
      "document_name": "Sales Contract",
      "document_tags": {}
    }
  }
}

Delete data

Similar to updates, when deleting data you also invoke an event indicating that data has been deleted and your users can decide how this should be reflected in their CRM.

Delete event is a special kind of update event where the user can decide whether they want to delete the corresponding entity in the CRM or maybe they just want to update it.

Therefore, you can provide some payload for the delete event so that in case the user wants to do an update they will have some data to work with.

Here's how handling of a delete event looks from the user's perspective:

Define delete event

Defining a delete event is identical to defining an update event with the sole difference of marking the type as delete.

To define a delete event, you'll pass an object to the events object of your CRM Object's definition in your CRM Link invocation with the following structure:

• Key: this is the slug of the event, which you'll use when invoking the event in the Xkit API
• Value: an object with the following structure
  • type: delete
  • name: the user-facing name of the event, e.g. "Contact Deleted"
  • description: the user-facing description of the event and how the user should handle it, e.g. "Occurs when a contact in our app is deleted"
  • payloadSchema: Xkit-flavored JSON describing the schema of the payload you'll provide when invoking the event

await linkCRM('example.xkit.co', token, {
  objects: {
    contact: {
      events: {
        contact_deleted: {
          type: "delete",
          label: "Contact Deleted",
          description: "Occurs when a contact in our app is deleted",
          payloadSchema: {
            deleted_at: {
              label: "Contact Delete Time",
              description: "ISO 8601 Date/Time representing when the contact was deleted",
              type: "string",
              format: "datetime"
            }
          }
        }
      }
    }
  }
})

Invoke delete event

Invoke the delete event by using the Invoke Event endpoint.

Since this is a delete event, the response will only have an id of the CRM record. The data property will be empty (even if the user decided to do an update)

Here's an example request and response for invoking a delete event for a CRM object with the slug contact, the CRM Record Contact:45322 and an event with the slug contact_deleted:

Request

POST /api/v1/crm/<connectionID>/objects/contact/Contact:45322/events/contact_deleted HTTP/1.1
Host: app.xkit.co
Authorization: Basic <credentials>

{
  "payload": {
    "deleted_at": "2022-05-17T23:17:53Z"
  }
}

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "record": {
    "type": "contact",
    "id": "Contact:45322",
    "data": { }
  }
}