How may we help?

Welcome to the support universe of OnlineFundraising where you will find help and guidance through our articles and videos. Please have a look and use the search function as needed. You are always welcome to contact our support in case there are any questions left unanswered.

Payment API

Contact

Senest redigeret:

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": 1,
  "pageSize": 50,
  "list": [
    {
      "contactGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
      "...": "..."
    },
    {
      "contactGuid": "c0f7cf91-1175-4283-9369-xxxxxxxxxxxx",
      "...": "..."
    }
  ]
}

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

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

Response

HTTP Description
200 OK
HTTP 200 Example
{
  "pageNumber": 1,
  "pageSize": 50,
  "list": [
    {
      "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"
      }
    ]
  }
]

Schema

Property Format and Description
contactGuid

string <uuid>

Unique Guid
merchantId

string

Unique ID of merchant
name

string
 

The full name of the Contact
birthDate

string <yyyy-MM-dd>

Date of birth
nationalId

string
 

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

string
 

Address line 1
address2

string
 

Address line 2
postCode

string
 

Postal code
city

string
 

City
countryCode

string
 

ISO formatted Country Code
msisdn

string
 

Phone with Country Code consisting of 1-3 digits reserved for country code without prefixes, such as 00.
email

string
 

Email of the contact
firstName

string
 

First name of the contact
lastName

string
 

Last name of the contact
companyName

string
 

Company name
businessCode

string
 

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

string
 

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

Enum: "individual", "business"
createdTs

string <yyyy-MM-dd HH:mm:ss zzzz>

Timestamp of creation
updatedTs

string <yyyy-MM-dd HH:mm:ss zzzz>
 

Timestamp of update
anonymizedTs

string <yyyy-MM-dd HH:mm:ss zzzz>
 

Timestamp of anonymization
archivedTs

string <yyyy-MM-dd HH:mm:ss zzzz>
 

Timestamp of archivation
externalId

string
 

An external ID as provided by an integrator or Merchant during migration
externalLink

string
 

An external URL available in the interface to e.g. CRM
originTs

string <yyyy-MM-dd HH:mm:ss zzzz>
 

Timestamp of origin, useful when importing data (e.g. if originated in external system)
mergeTargetGuid

string <uuid>

Unique Guid of merge target
mergeTs

string <yyyy-MM-dd HH:mm:ss zzzz>
 

Timestamp of merge

 

Example

{
"contactGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
"merchantId": "your-merchant",
"name": "John Doe",
"birthDate": "2019-12-31",
"nationalId": "061221xxxx",
"address": "Finsensvej 6E, 2.",
"address2": null,
"postCode": 1500,
"city": "Frederiksberg",
"countryCode": "DK",
"msisdn": 4535294855,
"email": "support@onlinefundraising.dk",
"firstName": "Jane",
"lastName": "Doe",
"companyName": "OnlineFundraising ApS",
"businessCode": 37273457,
"contactType": "business",
"createdTs": "2019-12-31 15:59:59 +0100",
"updatedTs": "2019-12-31 15:59:59 +0100",
"anonymizedTs": "2019-12-31 15:59:59 +0100",
"archivedTs": "2019-12-31 15:59:59 +0100",
"externalId": "some-id",
"externalLink": "string",
"originTs": "2019-12-31 15:59:59 +0100",
"mergeTargetGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
"mergeTs": "2019-12-31 15:59:59 +0100"
}

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

 

Was this article helpful?

0 out of 0 found this helpful

Related articles