Contacts

List Contacts

List all contacts. For more information see Contacts document model.

Endpoint:

URL	`/api/v2/contacts/`
Method	`GET`
Expected response code	`200`
Expected response type	`JSON`

Example:

BASH

curl -v \
    -H "Authorization: apikey $API_USER:$API_KEY" \
    $COREDATA_BASE_URL/api/v2/contacts/

Example response:

Contact list JSON

CODE

{
    "meta": {
        "limit": 20,
        "next": "/api/v2/contacts/?limit=20&offset=20",
        "offset": 0,
        "previous": null,
        "total_count": 1
    },
    "objects": [
        {
            "aspects": {},
            "contact_addresses": [],
            "contact_groups": [],
            "created": "2023-10-30T19:13:47",
            "created_by": null,
            "description": "",
            "dynatype": {
                "caption_plural": "dynatypes_labels:Organization_plural:",
                "caption_singular": "dynatypes_labels:Organization_singular:",
                "id": "709c96f6-7758-11ee-85ee-3f27b0b4a1c3",
                "title": "Organization"
            },
            "emails": [],
            "id": "73c2314c-7758-11ee-b86c-1b2d654e4cc1",
            "identifier": "",
            "modified": "2023-10-30T19:13:47",
            "modified_by": null,
            "organization": null,
            "path": "/domain/spaces/system/global/Contacts/John Doe",
            "phones": [],
            "resource_uri": "/api/v2/contacts/73c2314c-7758-11ee-b86c-1b2d654e4cc1/",
            "role": "contact_role:customer:",
            "snapshot_id": "73c24222-7758-11ee-b86c-13001748e5f5",
            "status": "contact_status:Active:",
            "tags": [],
            "template": null,
            "title": "John Doe",
            "type": "Contact",
            "urls": [],
            "version": "0.1"
        }
    ]
}

Result contacts are sorted by creation date ascending and then by ID ascending (to get stable sorting results).

List Favourite Contacts

See User home | List-favourite-Contacts.

Get Contact details

Get details of an existing Contact.

Endpoint:

URL	`/api/v2/contacts/$contact_id/`
Method	`GET`
Expected response code	`200`
Expected response type	`JSON`

URL parameters:

contact_id – ID of an existing contact to get details for.

Example:

BASH

contact_id=73c2314c-7758-11ee-b86c-1b2d654e4cc1

curl -v \
    -H "Authorization: apikey $API_USER:$API_KEY" \
    $COREDATA_BASE_URL/api/v2/contacts/$contact_id/

Where:

contact_id – ID of an existing contact.

Example response:

Contact details JSON

JSON

{
    "aspects": {},
    "contact_addresses": [],
    "contact_groups": [],
    "created": "2023-10-30T19:13:47",
    "created_by": null,
    "description": "",
    "dynatype": {
        "caption_plural": "dynatypes_labels:Organization_plural:",
        "caption_singular": "dynatypes_labels:Organization_singular:",
        "id": "709c96f6-7758-11ee-85ee-3f27b0b4a1c3",
        "title": "Organization"
    },
    "emails": [],
    "id": "73c2314c-7758-11ee-b86c-1b2d654e4cc1",
    "identifier": "",
    "modified": "2023-10-30T19:13:47",
    "modified_by": null,
    "organization": null,
    "path": "/domain/spaces/system/global/Contacts/John Doe",
    "phones": [],
    "resource_uri": "/api/v2/contacts/73c2314c-7758-11ee-b86c-1b2d654e4cc1/",
    "role": "contact_role:customer:",
    "snapshot_id": "73c24222-7758-11ee-b86c-13001748e5f5",
    "status": "contact_status:Active:",
    "tags": [],
    "template": null,
    "title": "John Doe",
    "type": "Contact",
    "urls": [],
    "version": "0.1"
}

Create Contact

Create a new contact.

Endpoint:

URL	`/api/v2/contacts/`
Method	`POST`
Content-Type	`JSON`
Expected response code	`201`

Request JSON body may contain the following fields:

Field	Type	Description	Mandatory
`title`	`String`	The name of the contact.	Yes
`identifier`	`String`	SSN (kennitala).	No
`status`	`String`	Contact status from `contact_status` values list. Example: `contact_status:Active:`.	No
`description`	`String`	Text description.	No
`emails`	`List[Dict]`	A list of emails and labels. Example: `[{"email": "eddie@memo.com", "label":"email_label:Work:"}]`.	No
`phones`	`List[Dict]`	A list of phone numbers and labels. Example: `[{"label": "phone_label:Work:", "number": "+44 7700 900504"}]`.	No
`contact_addresses`	`List[Dict]`	A list of addresses. Example: `[{"city": "Oxford", "code": "OX1 1BJ", "country": "country:United_Kingdom_of_Great_Britain_N_Ireland:europe", "state": "Cambridge", "street": "14th Charleston Road"}]`.	No
`urls`	`List[Dict]`	A list of URLs. Example: `[{"label": "url_label:Website:", "url": "http://www.eddieizzard.com/"}]`.	No
`parent`	`String`	ID of a `ContactFolder` in the https://wiselausnir.atlassian.net/wiki/spaces/CORE/pages/403144784/Global+Space. ID of an `Organization`. `[1]`	No
`organization`	`String`	ID of an `Organization` contact. `[2]`	No
`role`	`String`	A contact’s role. For available roles see the `contact_role` value list in CoreAdmin. E.g. `customer` value is available for the `contact_role` value list. Then the `role` field value passed to the endpoint must be `contact_role:customer:`.	No
`template`	`String`	ID of a contact template. There are predefined contact templates `Person` and `Organization`. By default, if the `template` is not provided, contacts are created based on `Organization` template. But more custom contact templates can be created.	No

[1] A Person contact can be created in ContactFolder or Organization. An Organization contact can only be created in ContactFolder.

[2] Only a Person contact can be created in Organization.

See Contacts document model for more details.

TODOs:

Describe contact creation using template.
Describe template values overriding when creating contact.

Create a Contact in default global Space

An Organizaation contact is created in the global space by default if no parent and organization parameters are provided.

Example:

BASH

title="John Doe"

curl -v \
    -X POST \
    -H "Authorization: apikey $API_USER:$API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"title\": \"$title\"}" \
    $COREDATA_BASE_URL/api/v2/contacts/

The response contains Location header having URL of the newly created contact, where we can can get the contact ID from:

CODE

Location: /api/v2/contacts/45330c2a-77da-11ee-81b1-0b61c7eec308/

The document path of the new Contact is:

CODE

/domain/spaces/system/global/Contacts/John Doe

Create a Contact in a ContactFolder

An Organization contact can be created in a certain ContactFolder.

Example:

BASH

contact_folder_id=65680e48-846c-11ee-8b63-77a168612873
title="John Doe"

curl -v \
    -X POST \
    -H "Authorization: apikey $API_USER:$API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"parent\": \"$contact_folder_id\", \"title\": \"$title\"}" \
    $COREDATA_BASE_URL/api/v2/contacts/

The response contains Location header with URL of the newly created Contact:

CODE

Location: /api/v2/contacts/c6976fec-846c-11ee-914c-2f3bdb64f9ef/

The document path of the new Contact is:

CODE

/domain/spaces/system/global/Contacts/ContactFolder-0/John Doe

Create a Person in an Organization

As by default contacts are created as Organization, and an Organization can not sit in another Organization, then to create a Person in an Organization we need to provide template parameter with Person template ID.

Example:

BASH

person_template_id=d95feda2-7f17-11ee-a7dc-d7778754bdc7
organization_id=c6976fec-846c-11ee-914c-2f3bdb64f9ef
title="John Doe"

curl -v \
    -X POST \
    -H "Authorization: apikey $API_USER:$API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"organization\": \"$organization_id\", \"template\": \"$person_template_id\", \"title\": \"$title\"}" \
    $COREDATA_BASE_URL/api/v2/contacts/

Response has Location header containing URL for the newly created contact:

NONE

Location: /api/v2/contacts/9fa9469c-84a5-11ee-b8b1-d7a342ab96d3/

For more information on using templates for document creation see CoreData domain model | Document-creation.

Update a Contact

Update an existing contact.

Endpoint:

URL	`/api/v2/contacts/$contact_id/`
Method	`PUT`
Content-Type	`JSON`
Expected response code	`204`

URL parameters:

contact_id – ID of an existing contact to update.

For supported body parameters see Create Contact section above.

Example:

BASH

contact_id=45330c2a-77da-11ee-81b1-0b61c7eec308
title="John Brown"

curl -v \
    -X PUT \
    -H "Authorization: apikey $API_USER:$API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"title\": \"$title\"}" \
    $COREDATA_BASE_URL/api/v2/contacts/$contact_id/

Move a Contact to the global ContactFolder

Example:

BASH

contact_id=9fa9469c-84a5-11ee-b8b1-d7a342ab96d3

curl -v \
    -X PUT \
    -H "Authorization: apikey $API_USER:$API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"parent\": \"\"}" \
    $COREDATA_BASE_URL/api/v2/contacts/$contact_id/

Contact’s document path before update:

CODE

/domain/spaces/system/global/Contacts/Some-ContactFolder/John Doe

Contact’s document path after update:

CODE

/domain/spaces/system/global/Contacts/John Doe

Move a Contact to a ContactFolder

Example:

BASH

contact_id=9fa9469c-84a5-11ee-b8b1-d7a342ab96d3
contact_folder_id=65680e48-846c-11ee-8b63-77a168612873

curl -v \
    -X PUT \
    -H "Authorization: apikey $API_USER:$API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"parent\": \"$contact_folder_id\"}" \
    $COREDATA_BASE_URL/api/v2/contacts/$contact_id/

Contact’s document path before update:

CODE

/domain/spaces/system/global/Contacts/John Doe

Contact’s document path after update:

CODE

/domain/spaces/system/global/Contacts/Some-ContactFolder/John Doe

Move a Person to an Organization

Example:

BASH

contact_id=9fa9469c-84a5-11ee-b8b1-d7a342ab96d3
ogranization_id=dd8dc638-7f17-11ee-8bc1-8b0841296ad4

curl -v \
    -X PUT \
    -H "Authorization: apikey $API_USER:$API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"organization\": \"$ogranization_id\"}" \
    $COREDATA_BASE_URL/api/v2/contacts/$contact_id/

Contact’s document path before update:

CODE

/domain/spaces/system/global/Contacts/Some-ContactFolder/John Doe

Contact’s document path after update:

CODE

/domain/spaces/system/global/Contacts/Some-Organization/John Doe

Delete Contact

Delete an existing contact.

Endpoint:

URL	`/api/v2/contacts/$contact_id/`
Method	`DELETE`
Expected response code	`204`

URL parameters:

contact_id – ID of an existing contact to update.

Example:

BASH

contact_id=45330c2a-77da-11ee-81b1-0b61c7eec308

curl -v \
    -X DELETE \
    -H "Authorization: apikey $API_USER:$API_KEY" \
    $COREDATA_BASE_URL/api/v2/contacts/$contact_id/

Create Comment for a Contact

See Comments | Create-Comment.

Contents

List Contacts

List Favourite Contacts

Get Contact details

Create Contact

Create a Contact in default global Space

Create a Contact in a ContactFolder

Create a Person in an Organization

Update a Contact

Move a Contact to the global ContactFolder

Move a Contact to a ContactFolder

Move a Person to an Organization

Delete Contact

Create Comment for a Contact