Create a company and associated contact

Last published: 2026-03-01

This guide is intended to demonstrate how Baack APIs can be used as a back end headless Customer Relationship Management system by example. In this guide we will create a company and a contact for that company using the APIs.

Concepts covered

Company Used to create a company representation in the context of your account company.
- Company representation and references.
- Organisation representation which owns your company. You may have multiple top level company accounts to separate concepts like test and production.
- Companies used to bootstrap your entry point for your existing companies.
- Identity endpoint used to create an identity associated with our customer company.
  - Person endpoint used to create a person associated with the identity.
    - Person Name endpoint used to create a name for the personal identity.
- Email address associated with the identity.
- Error error examples.

Overview

In this worked guide we will follow the workflow of requests involved in creating a company and a contact at the company. These concepts allow creation of a customer relationship data set and can be combined with other concepts from other parts of the API surface like tasks.

Step 1: Bootstrap companies list

The first step is to understand the existing company structures that the API token has access to. Recall from the getting started guide an API token is scoped to the owning company. Let's start by listing the companies in the scope of the current API token:


curl -H "Authorization: Bearer $TOKEN" http://localhost:8080/n/v1/companies
{
  "companies": [
    {
      "urn": "2ad858ab-51a9-11f0-b86c-d8bbc160a475",
      "url": "/n/v1/company/2ad858ab-51a9-11f0-b86c-d8bbc160a475"
    }
  ]
}

We can see here that our top level company is listed for the current API client.

**Note that the companies endpoint returns the company for which the token is provisioned and will also return other companies that have granted permission to the API client. Contact us to discuss cross company access.

Step 2: Create a new customer company

Now let's create a company. For an example of the kind of feedback the API gives, let's send an empty representation:

curl -X POST -H "Authorization: Bearer $TOKEN" http://localhost:8080/n/v1/company/ --data '{}'
{
  "httpCode": 400,
  "apiCode": "REPRESENTATION_MISSING_REQUIRED_FIELD",
  "detail": "name"
}

When authentication and authorisation have passed the API will provide meaningful feedback for developers about what needs to be addressed. This is key to making your developer experience effective.

Let's try a valid example with all of the required fields included:

curl -X POST -H "Authorization: Bearer $TOKEN" http://localhost:8080/n/v1/company/ --data '{"name":"Google", "owner":{"urn":"2ad747ab-51a9-11f0-b99c-d8bbc160a456"}}'

{
  "urn": "9fcc3481-6bdc-4504-ab56-6a617269a23e",
  "url": "/n/v1/company/9fcc3481-6bdc-4504-ab56-6a617269a23e",
  "name": "Google",
  "owner": {
    "urn": "2ad747ab-51a9-11f0-b99c-d8bbc160a611",
    "url": "/n/v1/company/2ad747ab-51a9-11f0-b99c-d8bbc160a456"
  },
  "entity": {
    "urn": "85587757-638f-424f-838f-e19f47c6c8e0",
    "url": "/n/v1/entity/85587757-638f-424f-838f-e19f47c6c8e0",
    "texts": [],
    "doubles": [],
    "dateTimes": [],
    "booleans": [],
    "images": [],
    "templates": [],
    "markdowns": []
  }
}

Now that we have a customer company created we can see a few other things in the response:

The endpoint has allocated a Unique Resource Name for the company.
There is a URL for accessing the company for further requests.
Our top level account company is referenced as the owner of the company representation.
The company has an associated content entity. This works just like any other content entity on the platform. You can use the content editor to capture arbitrary content with the company of all of the usual types.

Now that we have a company let's add the employee identity of the customer.

Step 3: Create an employee identity for our customer company

Looking at the identity endpoint reference we can see that an identity has two company references, the owner (for legal / data compliance purposes) and a companies reference. Let's go ahead and create a new identity for the customer company:

curl -X POST -H "Authorization: Bearer $TOKEN" http://localhost:8080/n/v1/identity/ --data '{"owner":{"urn":"2ad747ab-51a9-11f0-b99c-d8bbc160a456"}, "companies":[{"urn":"9fcc3481-6bdc-4504-ab56-6a617269a23e"}]}'

{
  "urn": "fe911610-13d3-43fb-b21e-6ae2b2745a85",
  "url": "/n/v1/identity/fe911610-13d3-43fb-b21e-6ae2b2745a85",
  "owner": {
    "urn": "2ad747ab-51a9-11f0-b99c-d8bbc160a456",
    "url": "/n/v1/company/2ad747ab-51a9-11f0-b99c-d8bbc160a611"
  },
  "name": "",
  "persons": [],
  "emails": [],
  "clientIdentifiers": [],
  "companies": []
}

OK, we have an identity, let's create the person associated with the identity

Step 4: Create a person contact details associated with the identity

Identities aren't people, and notably, Baack doesn't use a 'User' type model which is common to most username / password based login systems. We do have a user concept but these are limited to login related concepts.

It's also useful to be able to have an identity without necessarily knowing anything about a person for example at times like guest accounts.

Let's create our person, employee 1: Barry Sage

As we don't know their date of birth let's just create a person for now:

curl -X POST -H "Authorization: Bearer $TOKEN" http://localhost:8080/n/v1/person/ --data '{"identity":{"urn":"fe911610-13d3-43fb-b21e-6ae2b2745a85"}}'

{
  "urn": "cf36baeb-54ac-49fe-a9c9-ea3082ec943d",
  "url": "/n/v1/person/cf36baeb-54ac-49fe-a9c9-ea3082ec943d",
  "identity": {
    "urn": "fe911610-13d3-43fb-b21e-6ae2b2745a85",
    "url": "/n/v1/identity/fe911610-13d3-43fb-b21e-6ae2b2745a85"
  },
  "names": [],
  "telephones": [],
  "addresses": []
}

Step 5: Let's give the person a name

A person can be known by many different names so our platform supports this out of the box rather than being an afterthought. Let's create a name for the person we just created:

curl -X POST -H "Authorization: Bearer $TOKEN" http://localhost:8080/n/v1/personname/ --data '{"person":{"urn":"cf36baeb-54ac-49fe-a9c9-ea3082ec943d"}, "givenName":"Barry", "familyName":"Sage"}'
{
  "urn": "0023df98-8d0e-498d-b963-9d3329b21072",
  "url": "/n/v1/personname/0023df98-8d0e-498d-b963-9d3329b21072",
  "person": {
    "urn": "cf36baeb-54ac-49fe-a9c9-ea3082ec943d",
    "url": "/n/v1/person/cf36baeb-54ac-49fe-a9c9-ea3082ec943d"
  },
  "givenName": "Barry",
  "familyName": "Sage"
}

Step 6: Finally let's add an email address for our employee

Just like adding a person to our identity let's add the contact email address we have for the identity:

curl -X POST -H "Authorization: Bearer $TOKEN" http://localhost:8080/n/v1/email/ --data '{"identity":{"urn":"fe911610-13d3-43fb-b21e-6ae2b2745a85"}, "email":"noreply@google.com"}'

{
  "urn": "db003e35-03db-43f3-90fe-1e9fdb0d4fa0",
  "url": "/n/v1/email/db003e35-03db-43f3-90fe-1e9fdb0d4fa0",
  "identity": {
    "urn": "fe911610-13d3-43fb-b21e-6ae2b2745a85",
    "url": "/n/v1/identity/fe911610-13d3-43fb-b21e-6ae2b2745a85"
  },
  "email": "noreply@google.com"
}

Conclusion

We have created a company and an associated contact for that company. Let's take a look at these:

curl -H "Authorization: Bearer $TOKEN" http://localhost:8080/n/v1/identity/fe911610-13d3-43fb-b21e-6ae2b2745a85

{
  "urn": "fe911610-13d3-43fb-b21e-6ae2b2745a85",
  "url": "/n/v1/identity/fe911610-13d3-43fb-b21e-6ae2b2745a85",
  "owner": {
    "urn": "2ad747ab-51a9-11f0-b99c-d8bbc160a611",
    "url": "/n/v1/company/2ad747ab-51a9-11f0-b99c-d8bbc160a611"
  },
  "name": "",
  "persons": [
    {
      "urn": "cf36baeb-54ac-49fe-a9c9-ea3082ec943d",
      "url": "/n/v1/person/cf36baeb-54ac-49fe-a9c9-ea3082ec943d",
      "names": [
        {
          "urn": "0023df98-8d0e-498d-b963-9d3329b21072",
          "url": "/n/v1/personname/0023df98-8d0e-498d-b963-9d3329b21072",
          "givenName": "Barry",
          "familyName": "Sage"
        }
      ],
      "telephones": [],
      "addresses": []
    }
  ],
  "emails": [
    {
      "urn": "db003e35-03db-43f3-90fe-1e9fdb0d4fa0",
      "url": "/n/v1/email/db003e35-03db-43f3-90fe-1e9fdb0d4fa0",
      "email": "noreply@google.com"
    }
  ],
  "clientIdentifiers": [],
  "companies": [
    {
      "urn": "9fcc3481-6bdc-4504-ab56-6a617269a23e",
      "url": "/n/v1/company/9fcc3481-6bdc-4504-ab56-6a617269a23e"
    }
  ]
}

Now that we are all done let's clean up the dummy data

curl -X DELETE -H "Bearer-Token: $TOKEN" http://localhost:8080/n/v1/company/9fcc3481-6bdc-4504-ab56-6a617269a23e

Note deletes cascade so deleting a company will also delete all of the associated content, identities etc.