Create a contact via the API

In this exercise you create a complete contact via the API: an organisation with addresses and an associated person. The example shows how the objects involved work together – contacts, addresses and organisations are separate objects in teamspace that you link to one another.

The mental model first

• An organisation object organises contacts like a folder in a file system – it is not itself a contact, but needs a main contact that represents the entry in the address book.
• Addresses (postal, phone, email) are separate objects. A contact is not limited to a fixed number of addresses – you create as many as you need and link them.
• Via preferred addresses a person can be coupled to their organisation’s address: if the company address changes, the person’s work address automatically changes too.

The endpoints involved

Addresses, phone numbers and emails are all contact fields (contactfield). Their value is in vCard format ;;Street;City;;Postcode;Country; type is for example ADR (address), subtype for example WORK or HOME.

Step by step

1. Create the organisation contact – the main contact that represents the organisation in the address book (person: false):

POST /api/contact
{
  "active": true,
  "person": false,
  "lastname": "5 Point AG",
  "description": "Head office of 5 Point AG"
}

2. Create the postal address – as a separate contact field, linked to the contact you just created:

POST /api/contactfield
{
  "value": ";;Rheinstraße 40-42;Darmstadt;;64283;Germany",
  "type": "ADR",
  "subtype": "WORK",
  "contact": {{contactCreated}}
}

3. Create the organisation’s phone number – also as a contact field (analogous, with the matching type).

4. Create the organisation – the organisation object that references the address created earlier:

POST /api/organization
{
  "name": "5Point",
  "description": "Demo organisation",
  "address": {{contactCreated}}
}

5. Establish the links – update the organisation contact and connect it to the preferred address (mainAddress) and the organisation:

PUT /api/contact/{{contactCreated}}
{
  "active": true,
  "person": false,
  "mainAddress": {{contactfieldCreated}},
  "organization": {{organizationCreated}}
}

6. Create the person contact – now a person (person: true) for the existing organisation; they take over its address as their preferred address:

POST /api/contact
{
  "active": true,
  "person": true,
  "firstname": "Christoph",
  "lastname": "Preisser",
  "mainAddress": {{contactfieldCreated}},
  "organization": {{organizationCreated}}
}

7. Create the person’s email and phone – as further contact fields (POST /api/contactfield), provided the person has their own addresses that differ from the company’s.

The placeholders {{contactCreated}}, {{contactfieldCreated}} and {{organizationCreated}} stand for the IDs you take from the respective preceding responses.

Notes

• If you adopt the company address as the person’s preferred postal address, you keep it automatically up to date: a change to the company address feeds straight through to the person’s work address. The same principle applies to email and phone – use separate addresses only where the person genuinely differs.
• The addresses are created first and then linked to the contact – not the other way round. Plan the order accordingly when you automate the workflow.
• Which URL addresses which collection (contact, addresses, organisation) is clarified by the URL structure.

Related topics

• Create expenses & documents via the API API How-to
• API address structure (URLs) API Concept
• Topic: CRM CRM
• CRM software