Contact

A Contact represents the individual with whom we are dealing with and can either be a person or a business.

Changes committed to a Contact can be retrieved via the ChangeLog entity.

Properties

Name

Type

Mandatory

Default

Example

Description

Name

Type

Mandatory

Default

Example

Description

contactGuid

STRING

-





Unique GUID

merchantId

STRING

-





Readable ID of the merchant

name

STRING

NO



Fundraisingbureauet ApS

Full name of Contact

birthDate

DATE

NO





Birthday of Contact (YYYY-MM-DD)

nationalId

STRING

NO





National ID (i.e. CPR in Denmark provided without dashes)

address

STRING

NO



Store Kongensgade 59B, 3.

Address

address2

STRING

NO





Address line 2

postCode

STRING

NO



1264

Postcode

city

STRING

NO



København K

City

countryCode

STRING

NO



DK

ISO formatted Country Code (wiki)

msisdn

STRING

NO



4535294855

Phone with Country Code (wiki on Country Code) with 1-3 digits reserved for country code without prefixes, such as 00 (wiki on MSISDN).

email

STRING

NO



support@onlinefundraising.dk

Email of the Contact

firstName

STRING

NO





First name

lastName

STRING

NO





Last name

companyName

STRING

NO



Fundraisingbureauet ApS

Company name

businessCode

STRING

NO



37273457

Business Code (i.e. VAT, CVR in Denmark)

contactType

STRING

NO



individual, business

Type of Contact. Please note the value is not restricted to the examples given, however our form field will use these.

createdTs

TIMESTAMP

-





Timestamp of Contact creation

updatedTs

TIMESTAMP

-





Timestamp of last update

archivedTs

TIMESTAMP

-





Timestamp of archivation after which the Contact is hidden from queries.

externalId

STRING

NO





An external ID

externalLink

STRING

NO





An external URL to e.g. CRM

originTs

TIMESTAMP

NO





Timestamp of origin, useful when importing data

mergeTargetGuid

STRING

-





A GUID of that contact that this has been merged into.

mergeTs

TIMESTAMP

-





Timestamp of the merge operation.

The contactType property

As stated above the contactType property is not restricted to either "individual" or "business", however please note our form field will use these and show/hide the relevant fields upon selection.



individual

business



individual

business

name

v

x

firstName

v

v

lastName

v

v

companyName

x

v

nationalId

v

x

businessCode

x

v

address

v

v

postCode

v

v

city

v

v

countryCode

v

v

msisdn

v

v

 

GET /contacts?pageNumber={x}&pageSize={y}&archived=false|true

Get a list of Contacts at a given size by a given offset. Use "archived" (defaults to false) to focus your query. All parameters are optional.

Response

HTTP

Description

HTTP

Description

200

OK

HTTP 200 Example

1 2 3 4 5 6 7 8 9 10 11 12 13 14 { "pageNumber": {x}, "pageSize": {y}, "list": [ { "contactGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." }, { "contactGuid": "c0f7cf91-1175-4283-9369-xxxxxxxxxxxx", "...": "..." } ] }

 

GET /contacts?search={email|msisdn}

Get an array of Contacts by a given search string matching either email or msisdn (phone).

Response

HTTP

Description

HTTP

Description

200

OK

HTTP 200 Example

1 2 3 4 5 6 7 8 9 10 [ { "contactGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." }, { "contactGuid": "c0f7cf91-1175-4283-9369-xxxxxxxxxxxx", "...": "..." } ]

 

GET /contact/{guid}

Get a single Contact.

Response

HTTP

Description

HTTP

Description

200

OK

404

Contact was not found

HTTP 200 Example

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 { "contactGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "merchantId": "your-organisation", "name": "Jens Jensen", "birthDate": "2005-07-10", "nationalId": "1007059995", "address": "Store Kongensgade 59B", "address2": "", "postCode": "1264", "city": "København K", "countryCode": "DK", "msisdn": "4535294855", "email": "", "firstName": "Jens", "lastName": "Jensen", "companyName": "", "businessCode": "", "createdTs": "2019-12-31 15:59:59 +0100", "updatedTs": "", "archivedTs": "", "externalId": "", "externalLink": "" }

 

POST /contact

Insert a single Contact.

Please note our API accepts the given properties as is, and will not validate e.g. email, msisdn, nationalId, businessCode, address, birthDate, (full)name against given firstName and lastName.

Request

The following may be provided as the request body:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 { "name": "Jens Jensen", "birthDate": "2005-07-10", "nationalId": "1007059995", "address": "Store Kongensgade 59B", "address2": "", "postCode": "1264", "city": "København K", "countryCode": "DK", "msisdn": "4535294855", "email": "", "firstName": "Jens", "lastName": "Jensen", "companyName": "", "businessCode": "", "externalId": "", "externalLink": "" }

Response

HTTP

Description

HTTP

Description

201

Created

400

Something's wrong with request body.

HTTP 201 Example

1 2 3 4 { "contactGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." }

 

PUT /contact/{guid}

Replace a single Contact.

Request

The following may be provided as the request body:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 { "name": "Jens Jensen", "birthDate": "2005-07-10", "nationalId": "1007059995", "address": "Store Kongensgade 59B", "address2": "", "postCode": "1264", "city": "København K", "countryCode": "DK", "msisdn": "4535294855", "email": "", "firstName": "Jens", "lastName": "Jensen", "companyName": "", "businessCode": "", "externalId": "", "externalLink": "" }

Response

HTTP

Description

HTTP

Description

200

OK

400

Something's wrong with request body.

404

Contact was not found

HTTP 200 Example

1 2 3 4 { "contactGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." }

 

PATCH /contact/{guid}

Update a single Contact using add, replace or remove operations.

Request

The following must be provided as the request body:

1 2 3 4 5 6 7 [ { "op": "add|replace|remove", "path": "/address", "value": "Store Kongensgade 59A" } ]

Response

HTTP

Description

HTTP

Description

200

OK

400

Something's wrong with request body.

404

Contact was not found

 

POST /contact/{guid}/Anonymise

Anonymising a Contact will delete all properties revealing personal information, and then mark it archived to hide it from queries. This means the entity will as such be kept as it ties Subscriptions, Payment Methods and Payments together, which might be relevant later for accounting purposes.

Response

HTTP

Description

HTTP

Description

200

OK

400

Contact cannot be archived, most likely due to active Subscriptions

404

Contact was not found

 

POST /contact/{guid}/Archive

Archiving a Contact will hide it from queries.

Response

HTTP

Description

HTTP

Description

200

OK

400

Contact cannot be archived, most likely due to active Subscriptions

404

Contact was not found

 

POST /contact/{guid}/Merge

Merge two Contacts: a duplicate Contact defined in the endpoint URL and a target Contact defined in the request body.

A callback will be sent on a successful merge for the duplicate Contact being merged. Nothing is sent for the target Contact.
After a successful merge, the property mergeTargetGuid is set on the archived duplicate Contact.

Request

The following must be provided as the request body:

1 2 3 { "mergeTargetGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx" }

Response

HTTP

Description

HTTP

Description

200

OK

400

Something's wrong with request body

404

Either the duplicate or target guid was not found

 

POST /contact/{guid}/Unmerge

Unmerge two Contacts that were previously merged by specifying the guid of the Archived Contact. The endpoint will restore the archived Contact to its previous state with references to related entities.

Webhooks with type “Updated” will be sent for the unmerged Contact.

HTTP

Description

HTTP

Description

200

OK

400

Something's wrong with request body or the specified Contact has not been merged

404

Contact not found

 

GET /contact/{guid}/paymentMethods

Get a list of Payment Methods for a single Contact.

Response

HTTP

Description

HTTP

Description

200

OK

404

Contact was not found

HTTP 200 Example

1 2 3 4 5 6 7 8 9 10 11 12 [ { "contactGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "paymentMethodGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." }, { "contactGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "paymentMethodGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." } ]

 

GET /contact/{guid}/agreements

Get a list of Agreements for a single Contact.

Response

HTTP

Description

HTTP

Description

200

OK

404

Contact was not found

HTTP 200 Example

1 2 3 4 5 6 7 8 9 10 [ { "agreementGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." }, { "agreementGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." } ]

 

GET /contact/{guid}/addOns

Get a list of AddOns for a single Contact.

Response

HTTP

Description

HTTP

Description

200

OK

404

Contact was not found

HTTP 200 Example

1 2 3 4 5 6 7 8 9 10 [ { "addOnGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." }, { "addOnGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." } ]

 

GET /contact/{guid}/subscriptions

Get a list of Subscriptions for a single Contact.

Response

HTTP

Description

HTTP

Description

200

OK

404

Contact was not found

HTTP 200 Example

1 2 3 4 5 6 7 8 9 10 [ { "subscriptionGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." }, { "subscriptionGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." } ]

 

GET /contact/{guid}/payments

Get a list of Payments for a single Contact at a given size by a given offset.

Response

HTTP

Description

HTTP

Description

200

OK

404

Contact was not found

HTTP 200 Example

1 2 3 4 5 6 7 8 9 10 [ { "paymentGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." }, { "paymentGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." } ]

 

GET /contact/{guid}/receipts

Get a list of Receipts for a single Contact at a given size by a given offset.

Response

HTTP

Description

HTTP

Description

200

OK

404

Contact was not found

HTTP 200 Example

1 2 3 4 5 6 7 8 9 10 [ { "receiptGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." }, { "receiptGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." } ]

 

GET /contact/{guid}/log?limit={limit}

Get a list of changes to an Contact.

Response

HTTP

Description

HTTP

Description

200

OK

HTTP 200 Example

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 [ { "changeGuid": "242bf0de-5ed3-48a1-bb3a-xxxxxxxxxxxx", "createdTs": "2021-01-01 00:00:00 +0100", "entityType": "Contact", "entityGuid": "9a7c3665-5be0-4a5c-9641-xxxxxxxxxxxx", "changeTs": "2021-01-01 00:00:00 +0100", "oldEntityJson": "{ .. }", "changeDescription": "Updated by PUT request", "requester": "", "systemRequest": false, "changes": [ { "newValue": "John Arne", "oldValue": "John", "fieldName": "name" } ] } ]