Contacts are used to send out emails or link mediacontainers or licenses to a contact. Think of this controller as the door to your company’s address book.
| Flag | Description |
|---|---|
| 0 | Active |
| 1 | Trash |
| 10 | Autocreated – pending, request not confirmed |
| 11 | Permanently bounced email |
| 12 | Recipient-stop – user opted-out from receiving emails |
Reference
Find contacts
Returns one contact for the given contact id. Please note, that the response is an array!
GET/v5/contact/:id
Request Parameters
| Field | Type | Required | Description |
|---|---|---|---|
| ✗ | Fetch specific contact by email | ||
| id | integer | ✗ | Fetch specific contact by id |
| type | string | ✗ | type of the contact, e.g photographers. If not set all contacts are returned |
Response
| Field | Type | Description |
|---|---|---|
| createdAt | dateTime | Date and time of the creation |
| creatorId | integer | User id of the creator if this contact |
| customerId | integer | CustomerId this contact belongs to |
| E-Mail for this contact | ||
| flag | integer | Flag for this contact. See table above for details. |
| id | integer | ID of the contact |
| image | integer | id of the mediacontainer which holds the image. |
| jobId | string | If jobId is in response payload, the changes have not been applied immediately. Check activities! |
| lastEditorId | integer | User id of the last editor if this contact |
| metadata | array | Metadata for this contact. |
| └ title | string | Title of metadata |
| └ content | string | Title of metadata |
| settings | object | Settings for this contact. |
| └ origin | string | Origin of this contact, e.g. IPTC |
| object | Settings regarding contact email handling. | |
| └ disabled | boolean | If true, e-Mail is disabled |
| └ reason | string | Reason why email is disabled |
| └ lock | boolean | Lock contact against changes |
| └ lockUser | integer | UserId who lock this contact |
| └ deletionProtection | boolean | If true, contact is protected against deleton |
| └ deletionProtector | integer | UserId who activated deletion protection |
| └ metadataFields | array | These fields are shown on external pages. Deprecated |
| └ merge | object | Information regarding merge processes |
| └ conflicts | array | Array of objects containing conflicts from a merge process |
| type | string | type of the contact, e.g photographers. If not set all contacts are returned |
| uiLanguage | string | Language for this contact, e.g. for email templates |
| updatedAt | dateTime | Date and time of the latest update |
Create contacts
Creates a new contact.
POST/v6/contact
Request Parameters
| Field | Type | Required | Description |
|---|---|---|---|
| image | integer | ✗ | id of the mediacontainer which holds the image. See below for more details. |
| metadata | array | ✗ | Metadata for this contact. This is a new approach, which does not use contactMetadata controller. |
| settings | object | ✗ | Optional settings for this contact. If nothing send/set we will automatically add the key "metadataFields" and use the default definition which fields to show. |
| └ origin | string | ✗ | Origin of this contact, e.g. IPTC |
| object | ✗ | Settings regarding contact email handling. | |
| └ disabled | boolean | ✗ | If true, e-Mail is disabled |
| └ reason | string | ✗ | Reason why email is disabled |
| └ lock | boolean | ✗ | Lock contact against changes |
| └ lockUser | integer | ✗ | UserId who lock this contact |
| └ deletionProtection | boolean | ✗ | If true, contact is protected against deleton |
| └ deletionProtector | integer | ✗ | UserId who activated deletion protection |
| └ metadataFields | array | ✗ | These fields are shown on external pages. |
| └ merge | object | ✗ | Information regarding merge processes |
| └ conflicts | array | ✗ | Array of objects containing conflicts from a merge process |
| type | string | ✗ | contact type of this contact. Can be photographer etc. The type defines the available contact metadata fields. |
| uiLanguage | string | ✗ | Language for this contact, e.g. for email templates |
Response
| Field | Type | Description |
|---|---|---|
| createdAt | dateTime | Date and time of the creation |
| creatorId | integer | User id of the creator if this contact |
| customerId | integer | CustomerId this contact belongs to |
| E-Mail for this contact | ||
| flag | integer | Flag for this contact. See table above for details. |
| id | integer | ID of the contact |
| image | integer | id of the mediacontainer which holds the image. |
| jobId | string | If jobId is in response payload, the changes have not been applied immediately. Check activities! |
| lastEditorId | integer | User id of the last editor if this contact |
| metadata | array | Metadata for this contact. |
| └ title | string | Title of metadata |
| └ content | string | Title of metadata |
| settings | object | Settings for this contact. |
| └ origin | string | Origin of this contact, e.g. IPTC |
| object | Settings regarding contact email handling. | |
| └ disabled | boolean | If true, e-Mail is disabled |
| └ reason | string | Reason why email is disabled |
| └ lock | boolean | Lock contact against changes |
| └ lockUser | integer | UserId who lock this contact |
| └ deletionProtection | boolean | If true, contact is protected against deleton |
| └ deletionProtector | integer | UserId who activated deletion protection |
| └ metadataFields | array | These fields are shown on external pages. Deprecated |
| └ merge | object | Information regarding merge processes |
| └ conflicts | array | Array of objects containing conflicts from a merge process |
| type | string | contact type of this contact. Can be photographer etc. The type defines the available contact metadata fields. |
| uiLanguage | string | Language for this contact, e.g. for email templates |
| updatedAt | dateTime | Date and time of the latest update |
Update contacts
Updates an existing contact
PUT/v5/contact/:id
Request Parameters
| Field | Type | Required | Description |
|---|---|---|---|
| flag | integer | ✗ | Set flag for contact. Flag 11 is not available on public API. |
| id | integer | ✓ | ID of the contact to update |
| image | integer | ✗ | id of the mediacontainer which holds the image. See below for more details. |
| metadata | array | ✗ | Metadata for this contact. This is a new approach, which does not use contactMetadata controller. |
| sendOptInRequest | boolean | ✗ | If true the contact is actively marked as opt-in |
| settings | object | ✗ | Optional settings for this contact. If nothing send/set we will automatically add the key "metadataFields" and use the default definition which fields to show. |
| └ origin | string | ✗ | Origin of this contact, e.g. IPTC |
| object | ✗ | Settings regarding contact email handling. | |
| └ disabled | boolean | ✗ | If true, e-Mail is disabled |
| └ reason | string | ✗ | Reason why email is disabled |
| └ lock | boolean | ✗ | Lock contact against changes |
| └ lockUser | integer | ✗ | UserId who lock this contact |
| └ deletionProtection | boolean | ✗ | If true, contact is protected against deleton |
| └ deletionProtector | integer | ✗ | UserId who activated deletion protection |
| └ metadataFields | array | ✗ | These fields are shown on external pages. |
| └ merge | object | ✗ | Information regarding merge processes |
| └ conflicts | array | ✗ | Array of objects containing conflicts from a merge process |
| type | string | ✗ | contact type of this contact. Can be photographer etc. The type defines the available contact metadata fields. |
Response
| Field | Type | Description |
|---|---|---|
| createdAt | dateTime | Date and time of the creation |
| creatorId | integer | User id of the creator if this contact |
| customerId | integer | CustomerId this contact belongs to |
| E-Mail for this contact | ||
| flag | integer | Flag for this contact. See table above for details. |
| id | integer | ID of the contact |
| image | integer | id of the mediacontainer which holds the image. |
| jobId | string | If jobId is in response payload, the changes have not been applied immediately. Check activities! |
| lastEditorId | integer | User id of the last editor if this contact |
| metadata | array | Metadata for this contact. |
| └ title | string | Title of metadata |
| └ content | string | Title of metadata |
| settings | object | Settings for this contact. |
| └ origin | string | Origin of this contact, e.g. IPTC |
| object | Settings regarding contact email handling. | |
| └ disabled | boolean | If true, e-Mail is disabled |
| └ reason | string | Reason why email is disabled |
| └ lock | boolean | Lock contact against changes |
| └ lockUser | integer | UserId who lock this contact |
| └ deletionProtection | boolean | If true, contact is protected against deleton |
| └ deletionProtector | integer | UserId who activated deletion protection |
| └ metadataFields | array | These fields are shown on external pages. Deprecated |
| └ merge | object | Information regarding merge processes |
| └ conflicts | array | Array of objects containing conflicts from a merge process |
| type | string | contact type of this contact. Can be photographer etc. The type defines the available contact metadata fields. |
| uiLanguage | string | Language for this contact, e.g. for email templates |
| updatedAt | dateTime | Date and time of the latest update |
Destroy contacts
DELETE/v5/contact/:id
Request Parameters
| Field | Type | Required | Description |
|---|---|---|---|
| forceDelete | boolean | ✗ | If set to true, the contact is moved to trash, all relations are deleted. |
| forceDeleteContact | boolean | ✗ | If set to true, the contact is destroyed. |
| id | integer | ✓ | ID of the contact to delete |
| move | integer | ✗ |
Response
| Field | Type | Description |
|---|---|---|
| affectedLicenses | array | |
| id | integer | ID of the contact |
| jobId | string | If jobId is in response payload, the changes have not been applied immediately. Check activities! |
| move | integer |
Destroys a contact. If the contact is related to a license or a mediacontainer you cannot destroy it right away. You have to assign a new contact to the linked resources (at least for licenses).