Karia
Guides

Creating your first contact

A practical first workflow for creating and enriching a contact record

Creating Your First Contact

Creating a contact is a good first integration workflow because it exercises authentication, organisation discovery, workspace discovery, and a write operation against a workspace-scoped resource.

Workflow

  1. Fetch organisations with GET /organisation.
  2. Fetch workspaces for the selected organisation with GET /organisation/{orgId}/workspace.
  3. Create a contact with POST /organisation/{orgId}/workspace/{workspaceId}/contact.
  4. Optionally attach an address with POST /organisation/{orgId}/workspace/{workspaceId}/contact/{contactId}/address.
  5. Optionally attach a communication method with POST /organisation/{orgId}/workspace/{workspaceId}/contact/{contactId}/method.

List organisations

Start by finding the organisation you want to create the contact under. Use the selected organisation ID in the next step.
Open reference
GET/organisation
Authorizationv
{
  "type": "Bearer API key"
}
Pathv
Endpoint
/organisation
Operation ID
organisation.list
Bodyv
{
  "response": {
    "organisations": [
      {
        "id": "org_123",
        "name": "Example Organisation"
      }
    ]
  }
}

List workspaces

Fetch the available workspaces for the selected organisation. Most contact operations are scoped to both organisation and workspace.
Open reference
GET/organisation/{orgId}/workspace
Authorizationv
{
  "type": "Bearer API key"
}
Pathv
Endpoint
/organisation/{orgId}/workspace
{
  "orgId": "org_123"
}
Operation ID
workspace.list
Bodyv
{
  "response": {
    "workspaces": [
      {
        "id": "workspace_123",
        "name": "Sales"
      }
    ]
  }
}

Create the contact

Create the contact record in the selected workspace. Include any known contact methods so the workspace can reach the customer.
Open reference
POST/organisation/{orgId}/workspace/{workspaceId}/contact
Authorizationv
{
  "type": "Bearer API key"
}
Pathv
Endpoint
/organisation/{orgId}/workspace/{workspaceId}/contact
{
  "orgId": "org_123",
  "workspaceId": "workspace_123"
}
Operation ID
contact.create
Bodyv
{
  "firstName": "Jane",
  "lastName": "Citizen",
  "preferredName": "Jane",
  "contactMethods": [
    {
      "value": "jane.citizen@example.com",
      "type": "email"
    },
    {
      "value": "+61400111222",
      "type": "phone"
    }
  ]
}

Optionally add an address

Attach address details after the contact exists when your workflow captures residential or mailing address information.
Open reference
POST/organisation/{orgId}/workspace/{workspaceId}/contact/{contactId}/address
Authorizationv
{
  "type": "Bearer API key"
}
Pathv
Endpoint
/organisation/{orgId}/workspace/{workspaceId}/contact/{contactId}/address
{
  "orgId": "org_123",
  "workspaceId": "workspace_123",
  "contactId": "contact_123"
}
Operation ID
contact.address.create
Bodyv
{
  "type": "current",
  "streetNumber": "10",
  "streetName": "Example Street",
  "suburb": "Sydney",
  "state": "NSW",
  "postcode": "2000",
  "country": "Australia"
}

Optionally add another contact method

Add additional communication methods if they are collected later in the flow.
Open reference
POST/organisation/{orgId}/workspace/{workspaceId}/contact/{contactId}/method
Authorizationv
{
  "type": "Bearer API key"
}
Pathv
Endpoint
/organisation/{orgId}/workspace/{workspaceId}/contact/{contactId}/method
{
  "orgId": "org_123",
  "workspaceId": "workspace_123",
  "contactId": "contact_123"
}
Operation ID
contact.method.create
Bodyv
{
  "value": "jane.citizen@example.com",
  "type": "email"
}

Guides Overview

Endpoint-specific guides for the beta API surface

Submitting your first deal

Send a sales lead to Karia by creating a contact and then an origination deal

On this page

Creating Your First ContactWorkflowRelated OpenAPI OperationsRelated Docs