How may we help?

Introduction

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.

Endpoints

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
200	OK

HTTP 200 Example

{
  "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
200	OK

HTTP 200 Example

[
  {
    "contactGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
    "...": "..."
  },
  {
    "contactGuid": "c0f7cf91-1175-4283-9369-xxxxxxxxxxxx",
    "...": "..."
  }
]

GET /contact/{guid}

Get a single Contact.

Response

HTTP	Description
200	OK
404	Contact was not found

HTTP 200 Example

{
  "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:

{
  "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
201	Created
400	Something's wrong with request body.

HTTP 201 Example

{
  "contactGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
  "...": "..."
}

PUT /contact/{guid}

Replace a single Contact.

Request

The following may be provided as the request body:

{
  "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
200	OK
400	Something's wrong with request body.
404	Contact was not found

HTTP 200 Example

{
  "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:

[
  {
    "op": "add|replace|remove",
    "path": "/address",
    "value": "Store Kongensgade 59A"
  }
]

Response

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
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
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:

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

Response

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
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
200	OK
404	Contact was not found

HTTP 200 Example

[
  {
    "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}/subscriptions

Get a list of Subscriptions for a single Contact.

Response

HTTP	Description
200	OK
404	Contact was not found

HTTP 200 Example

[
  {
    "subscriptionGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
    "...": "..."
  },
  {
    "subscriptionGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
    "...": "..."
  }
]

GET /contact/{guid}/agreements

Get a list of Agreements for a single Contact.

Response

HTTP	Description
200	OK
404	Contact was not found

HTTP 200 Example

[
  {
    "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
200	OK
404	Contact was not found

HTTP 200 Example

[
  {
    "addOnGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
    "...": "..."
  },
  {
    "addOnGuid": "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
200	OK
404	Contact was not found

HTTP 200 Example

[
  {
    "paymentGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
    "...": "..."
  },
  {
    "paymentGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
    "...": "..."
  }
]

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

Get a list of changes to a Contact.

Response

HTTP	Description
200	OK

HTTP 200 Example

[
  {
    "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"
      }
    ]
  }
]

Properties

Name	Type	Mandatory	Default	Example	Description
contactGuid	STRING	-			Unique GUID
merchantId	STRING	-			Readable ID of the merchant
name	STRING	NO		OnlineFundraising 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		Finsensvej 6E, 2.	Address
address2	STRING	NO			Address line 2
postCode	STRING	NO		2000	Postcode
city	STRING	NO		Frederiksberg	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		OnlineFundraising 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
anonymizedTs	TIMESTMAP	-			Timestamp of anonymisation.
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
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