Create a contact

POST

/contacts

const url = 'https://api.de.teamgrid.app/v1/contacts';
const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': 'example',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"birthday":"2026-04-15T12:00:00Z","category":"customer","companyTitle":"example","customerId":"example","emails":[{"email":"example","type":"business"}],"firstName":"example","gender":"female","groupId":"example","lastName":"example","nickname":"example","notes":"example","parentContactId":"example","phoneNumbers":[{"number":"example","type":"business"}],"salutation":"example","type":"company"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.de.teamgrid.app/v1/contacts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example' \
  --data '{ "birthday": "2026-04-15T12:00:00Z", "category": "customer", "companyTitle": "example", "customerId": "example", "emails": [ { "email": "example", "type": "business" } ], "firstName": "example", "gender": "female", "groupId": "example", "lastName": "example", "nickname": "example", "notes": "example", "parentContactId": "example", "phoneNumbers": [ { "number": "example", "type": "business" } ], "salutation": "example", "type": "company" }'

Authorizations

bearerAuth

Parameters

Header Parameters

Idempotency-Key

required

string

>= 1 characters <= 128 characters /^[!-~]+$/

Unique request key retained for seven days. Within that window, reuse with different data is rejected.

Request Body^required

application/json

object

birthday

string | null format: date-time

category

string | null

Allowed values: customer supplier

companyTitle

string | null

<= 500 characters

customerId

string | null

<= 500 characters

emails

Array<object> | null

<= 100 items

object

email

required

string

>= 1 characters <= 500 characters

type

required

string

Allowed values: business other private

firstName

string | null

<= 500 characters

gender

string | null

Allowed values: female male

groupId

string | null

<= 128 characters

lastName

string | null

<= 500 characters

nickname

string | null

<= 500 characters

notes

string | null

<= 50000 characters

parentContactId

string | null

<= 128 characters

phoneNumbers

Array<object> | null

<= 100 items

object

number

required

string

>= 1 characters <= 500 characters

type

required

string

Allowed values: business direct fax landline mobile other

salutation

string | null

<= 500 characters

type

required

string

Allowed values: company person

Responses

200

An idempotent replay of an existing resource.

application/json

object

data

required

object

attributes

required

object

archived

required

boolean

birthday

required

string | null format: date-time

category

required

string | null

companyTitle

required

string

createdAt

required

string | null format: date-time

customerId

required

string | null

emails

required

Array<object>

object

email

required

string

type

required

string

firstName

required

string

gender

required

string | null

groupId

required

string | null

lastName

required

string

nickname

required

string

notes

required

string

parentContactId

required

string | null

phoneNumbers

required

Array<object>

object

number

required

string

type

required

string

salutation

required

string

type

required

string

Allowed values: person company

updatedAt

required

string | null format: date-time

required

string

type

required

Allowed value: contact

meta

required

object

requestId

required

string

Example

{
  "data": {
    "attributes": {
      "type": "person"
    },
    "type": "contact"
  }
}

Headers

Idempotency-Replayed

string

Allowed values: true

201

A newly created resource.

application/json

object

data

required

object

attributes

required

object

archived

required

boolean

birthday

required

string | null format: date-time

category

required

string | null

companyTitle

required

string

createdAt

required

string | null format: date-time

customerId

required

string | null

emails

required

Array<object>

object

email

required

string

type

required

string

firstName

required

string

gender

required

string | null

groupId

required

string | null

lastName

required

string

nickname

required

string

notes

required

string

parentContactId

required

string | null

phoneNumbers

required

Array<object>

object

number

required

string

type

required

string

salutation

required

string

type

required

string

Allowed values: person company

updatedAt

required

string | null format: date-time

required

string

type

required

Allowed value: contact

meta

required

object

requestId

required

string

Example

{
  "data": {
    "attributes": {
      "type": "person"
    },
    "type": "contact"
  }
}

Headers

Idempotency-Replayed

string

Allowed values: false

400

The request is invalid.

application/json

object

errors

required

Array<object>

object

code

required

string

detail

required

string

source

object

key

additional properties

string

status

required

string

/^[1-5][0-9]{2}$/

title

required

string

meta

required

object

requestId

required

string

Example^generated

{
  "errors": [
    {
      "code": "example",
      "detail": "example",
      "source": {
        "additionalProperty": "example"
      },
      "status": "example",
      "title": "example"
    }
  ],
  "meta": {
    "requestId": "example"
  }
}

401

The bearer credential is missing, invalid, expired, or revoked.

application/json

object

errors

required

Array<object>

object

code

required

string

detail

required

string

source

object

key

additional properties

string

status

required

string

/^[1-5][0-9]{2}$/

title

required

string

meta

required

object

requestId

required

string

Example^generated

{
  "errors": [
    {
      "code": "example",
      "detail": "example",
      "source": {
        "additionalProperty": "example"
      },
      "status": "example",
      "title": "example"
    }
  ],
  "meta": {
    "requestId": "example"
  }
}

403

The credential has insufficient scope.

application/json

object

errors

required

Array<object>

object

code

required

string

detail

required

string

source

object

key

additional properties

string

status

required

string

/^[1-5][0-9]{2}$/

title

required

string

meta

required

object

requestId

required

string

Example^generated

{
  "errors": [
    {
      "code": "example",
      "detail": "example",
      "source": {
        "additionalProperty": "example"
      },
      "status": "example",
      "title": "example"
    }
  ],
  "meta": {
    "requestId": "example"
  }
}

409

The request conflicts with the current resource state.

application/json

object

errors

required

Array<object>

object

code

required

string

detail

required

string

source

object

key

additional properties

string

status

required

string

/^[1-5][0-9]{2}$/

title

required

string

meta

required

object

requestId

required

string

Example^generated

{
  "errors": [
    {
      "code": "example",
      "detail": "example",
      "source": {
        "additionalProperty": "example"
      },
      "status": "example",
      "title": "example"
    }
  ],
  "meta": {
    "requestId": "example"
  }
}

429

The credential or source exceeded its rate limit.

application/json

object

errors

required

Array<object>

object

code

required

string

detail

required

string

source

object

key

additional properties

string

status

required

string

/^[1-5][0-9]{2}$/

title

required

string

meta

required

object

requestId

required

string

Example^generated

{
  "errors": [
    {
      "code": "example",
      "detail": "example",
      "source": {
        "additionalProperty": "example"
      },
      "status": "example",
      "title": "example"
    }
  ],
  "meta": {
    "requestId": "example"
  }
}

Headers

Retry-After

integer

>= 1

Minimum delay in seconds before retrying.

X-RateLimit-Limit

integer

Maximum requests in the current window.

X-RateLimit-Remaining

integer

Requests remaining in the current window.

X-RateLimit-Reset

integer

Unix time in milliseconds when the current window resets.

X-Request-Id

string

Request correlation identifier.

502

The cell-local application returned an invalid response.

application/json

object

errors

required

Array<object>

object

code

required

string

detail

required

string

source

object

key

additional properties

string

status

required

string

/^[1-5][0-9]{2}$/

title

required

string

meta

required

object

requestId

required

string

Example^generated

{
  "errors": [
    {
      "code": "example",
      "detail": "example",
      "source": {
        "additionalProperty": "example"
      },
      "status": "example",
      "title": "example"
    }
  ],
  "meta": {
    "requestId": "example"
  }
}

503

A required cell-local dependency is unavailable.

application/json

object

errors

required

Array<object>

object

code

required

string

detail

required

string

source

object

key

additional properties

string

status

required

string

/^[1-5][0-9]{2}$/

title

required

string

meta

required

object

requestId

required

string

Example^generated

{
  "errors": [
    {
      "code": "example",
      "detail": "example",
      "source": {
        "additionalProperty": "example"
      },
      "status": "example",
      "title": "example"
    }
  ],
  "meta": {
    "requestId": "example"
  }
}

Create a contact

Authorizations

Parameters

Header Parameters

Request Bodyrequired

Responses

200

Example

Headers

201

Example

Headers

400

Examplegenerated

401

Examplegenerated

403

Examplegenerated

409

Examplegenerated

429

Examplegenerated

Headers

502

Examplegenerated

503

Examplegenerated

Request Body^required

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated