Skip to content
/
Assign an action to a cus...

Adfin API (1.0.0)

Adfin uses OAuth 2.0 access tokens to authenticate all API requests.

There are two contexts in which tokens are issued:

  • Biller Access Tokens — Generated via the Authorization Code flow when a biller connects their Adfin account. These tokens grant access to that biller's data (invoices, payment requests, customers, etc.).

  • Platform Access Tokens — Generated via the Client Credentials flow when a platform authenticates as itself rather than as one of its billers. A platform uses one to manage its own webhook subscriptions under /api/apps/{clientId}/webhooks.

Download OpenAPI description
direct-integration-api-reference.json
direct-integration-api-reference.yaml
Languages
Servers
Mock server
https://developer.adfin.com/_mock/products/direct-integration/direct-integration-api-reference/
Production API Server URL
https://api.adfin.com/api/
Staging API Server URL
https://api.staging.adfin.com/api/

oAuth2

Operations

Biller

Operations

Verifications

Operations

Customers

Operations

Retrieve a list of customers by filter

Request

Security
Biller Access Token (Staging) or Biller Access Token (Production)
Query
onlyCustomersWithActivityboolean

Filter customers that have any financial activity (invoices, direct debits)

searchTextstring

Fuzzy search a customer based on a text

ddMandateSignedStartTimestring(date-time)

Filter customers that have signed their direct debit mandate after this date

ddMandateSignedEndTimestring(date-time)

Filter customers that have signed their direct debit mandate until this date

ddMandateStatusesArray of strings

The status of the latest direct debit mandate

Items Enum"CREATED""PENDING""ACTIVE""PENDING_CANCELLATION""CANCELLED""MIGRATING"
includeCustomerFinancialDetailsboolean

This flag determines whether the response should include the financial status of the customer's invoices and payments

financialStatusesArray of strings

The financial statuses of the payment situation of the customer

Items Enum"DRAFT""OUTSTANDING""PENDING_PAYMENTS""OVERDUE""FULLY_PAID""NO_INVOICES"
lastUpdatedStartTimestring(date-time)

The start time after which the customer last updated time should be, including the start time.

tagIdsArray of strings(uuid)

The tag ids of the customer

customerIdsArray of strings(uuid)

The ids of the customers

pageinteger>= 0

Zero-based page index (0..N)

Default 0
sizeinteger>= 1

The size of the page to be returned

Default 20
sortArray of strings

Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.

Default ["creationTime,DESC"]
curl -i -X GET \
  'https://developer.adfin.com/_mock/products/direct-integration/direct-integration-api-reference/customers?onlyCustomersWithActivity=true&searchText=string&ddMandateSignedStartTime=2019-08-24T14%3A15%3A22Z&ddMandateSignedEndTime=2019-08-24T14%3A15%3A22Z&ddMandateStatuses=CREATED&includeCustomerFinancialDetails=true&financialStatuses=DRAFT&lastUpdatedStartTime=2019-08-24T14%3A15%3A22Z&tagIds=497f6eca-6276-4993-bfeb-53cbbbba6f08&customerIds=497f6eca-6276-4993-bfeb-53cbbbba6f08&page=0&size=20&sort=creationTime%2CDESC' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

The list of customers for the specified filter.

Bodyapplication/json
customersArray of objects(CustomerResponse)

The list of customers for the specified filter.

pageobject(Pagination)
paginationobject(Pagination)
Response
application/json
{
  "customers": [
    { … }
  ],
  "page": {
    "page": 0,
    "size": 0,
    "totalPages": 0,
    "totalElements": 0,
    "numberOfElements": 0,
    "sort": "string"
  },
  "pagination": {
    "page": 0,
    "size": 0,
    "totalPages": 0,
    "totalElements": 0,
    "numberOfElements": 0,
    "sort": "string"
  }
}

Update a customer

Request

Security
Biller Access Token (Staging) or Biller Access Token (Production)
Bodyapplication/jsonrequired
idstringrequired

The Adfin id of the customer.

externalIdstring

The id of the customer from the platform that is integrating with Adfin.

namestring

The full name of the customer.

peopleArray of objects(Person)

The list of people assigned to the customer.

addressesArray of objects(Address)

The list of the addresses for the customer. Only 1 pe supported for now

externalDataobject(CustomerExternalData)
trackingItemIdsArray of strings(uuid)

The list of tracking item catalogue IDs associated with the customer.

officeIdstring(uuid)

The office ID associated with the customer.

collectionAgentIdstring(uuid)

The collection agent ID to associate with the customer.

curl -i -X PUT \
  https://developer.adfin.com/_mock/products/direct-integration/direct-integration-api-reference/customers \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "string",
    "externalId": "string",
    "name": "string",
    "people": [
      {
        "id": "string",
        "firstName": "string",
        "lastName": "string",
        "email": "string",
        "phoneNo": "string",
        "isPrimaryContact": true,
        "isIncludedInCommunications": true,
        "validForEmailCommunication": true,
        "validForPhoneCommunication": true
      }
    ],
    "addresses": [
      {
        "city": "string",
        "postalCode": "string",
        "country": "st",
        "addressLine1": "string"
      }
    ],
    "externalData": {
      "connectorType": "XERO",
      "id": "string",
      "name": "string"
    },
    "trackingItemIds": [
      "497f6eca-6276-4993-bfeb-53cbbbba6f08"
    ],
    "officeId": "da08ce10-cc2b-4a3d-a418-e10a176cc27a",
    "collectionAgentId": "fe30a7f6-c47c-4051-9601-bd9dbc464447"
  }'

Responses

The request has succeeded and has resulted in one customer being updated.

Bodyapplication/json
idstring

The Adfin id of the customer.

externalIdstring

The id of the customer from the platform that is integrating with Adfin.

namestring

The full name of the customer.

creationTimestring(date-time)

The time the customer was created.

lastUpdatedTimestring(date-time)

The last time when the customer was updated.

peopleArray of objects(Person)

The list of people assigned to the customer.

addressesArray of objects(Address)

The list of the addresses for the customer.

directDebitMandateobject(DirectDebitMandateSummary)
billerBankAccountobject(CustomerBankAccount)
timezonestring

The timezone of the customer.

discountobject(CustomerDiscount)
externalDataArray of objects(CustomerExternalData)

References about this customer from external platforms Adfin integrates with, such as ID, etc.

tagsArray of strings

The tag ids associated with the customer.

statusstring

The status of the customer (ACTIVE, ARCHIVED)

Enum"ACTIVE""ARCHIVED"
statusReasonCodestring

The reason as a predefined code for why the customer is in a certain status

Enum"MERGED""ARCHIVED_MANUALLY"
settingsobject(CustomerSettingsResponse)
trackingItemsArray of objects(TrackingItemCatalogueResponse)

The tracking item catalogues associated with the customer.

officeobject(InvoiceOfficeResponse)
collectionAgentIdstring(uuid)

The collection agent ID associated with the customer.

Response
application/json
{
  "id": "string",
  "externalId": "string",
  "name": "string",
  "creationTime": "2019-08-24T14:15:22Z",
  "lastUpdatedTime": "2019-08-24T14:15:22Z",
  "people": [
    { … }
  ],
  "addresses": [
    { … }
  ],
  "directDebitMandate": {
    "id": "string",
    "status": "CREATED",
    "statusReasonCode": "PENDING_DD_CAPABILITY",
    "statusReason": "string",
    "creationTime": "2019-08-24T14:15:22Z",
    "lastUpdatedTime": "2019-08-24T14:15:22Z",
    "authorisationTime": "2019-08-24T14:15:22Z",
    "submissionTime": "2019-08-24T14:15:22Z",
    "url": "string",
    "bankAccountNumber": "string",
    "personId": "string",
    "distributionTime": "2019-08-24T14:15:22Z",
    "lastNotificationSentTime": "2019-08-24T14:15:22Z"
  },
  "billerBankAccount": {
    "accountHolderAddress": { … },
    "accountHolderName": "string",
    "bankAccount": { … },
    "bankAddress": { … },
    "currencyCode": "AED"
  },
  "timezone": "string",
  "discount": {
    "percentage": 0,
    "period": 0
  },
  "externalData": [
    { … }
  ],
  "tags": [
    "string"
  ],
  "status": "ACTIVE",
  "statusReasonCode": "MERGED",
  "settings": {
    "paymentSettings": { … }
  },
  "trackingItems": [
    { … }
  ],
  "office": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "string",
    "trackingItemId": "c7c7fc03-0b17-402e-aa79-1d532a6db210",
    "details": { … }
  },
  "collectionAgentId": "fe30a7f6-c47c-4051-9601-bd9dbc464447"
}

Create a customer

Request

Security
Biller Access Token (Staging) or Biller Access Token (Production)
Bodyapplication/jsonrequired
namestring

The full name of the customer.

Example: "John Doe"
peopleArray of objects(Person)

A list of people associated with the customer. Can include contacts, representatives, or stakeholders.

Example: [{"name":"Jane Smith","email":"jane.smith@example.com"}]
addressesArray of objects(Address)

A list of addresses for the customer. Currently, only one address is supported.

Example: [{"line1":"2 Catherine Pl","city":"London","state":"NY","postCode":"SW1E 6HF"}]
externalDataobject(CustomerExternalData)
Example: {"connectorType":"QuickBooks","id":"QB-56789","name":"My First Customer"}
trackingItemIdsArray of strings(uuid)

The list of tracking item catalogue IDs associated with the customer.

officeIdstring(uuid)

The office ID associated with the customer.

collectionAgentIdstring(uuid)

The collection agent ID to associate with the customer.

curl -i -X POST \
  https://developer.adfin.com/_mock/products/direct-integration/direct-integration-api-reference/customers \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "John Doe",
    "people": [
      {
        "name": "Jane Smith",
        "email": "jane.smith@example.com"
      }
    ],
    "addresses": [
      {
        "line1": "2 Catherine Pl",
        "city": "London",
        "state": "NY",
        "postCode": "SW1E 6HF"
      }
    ],
    "externalData": {
      "connectorType": "XERO",
      "id": "string",
      "name": "string"
    },
    "trackingItemIds": [
      "497f6eca-6276-4993-bfeb-53cbbbba6f08"
    ],
    "officeId": "da08ce10-cc2b-4a3d-a418-e10a176cc27a",
    "collectionAgentId": "fe30a7f6-c47c-4051-9601-bd9dbc464447"
  }'

Responses

The request has succeeded and has resulted in one customer being updated.

Bodyapplication/json
idstring

The Adfin id of the customer.

externalIdstring

The id of the customer from the platform that is integrating with Adfin.

namestring

The full name of the customer.

creationTimestring(date-time)

The time the customer was created.

lastUpdatedTimestring(date-time)

The last time when the customer was updated.

peopleArray of objects(Person)

The list of people assigned to the customer.

addressesArray of objects(Address)

The list of the addresses for the customer.

directDebitMandateobject(DirectDebitMandateSummary)
billerBankAccountobject(CustomerBankAccount)
timezonestring

The timezone of the customer.

discountobject(CustomerDiscount)
externalDataArray of objects(CustomerExternalData)

References about this customer from external platforms Adfin integrates with, such as ID, etc.

tagsArray of strings

The tag ids associated with the customer.

statusstring

The status of the customer (ACTIVE, ARCHIVED)

Enum"ACTIVE""ARCHIVED"
statusReasonCodestring

The reason as a predefined code for why the customer is in a certain status

Enum"MERGED""ARCHIVED_MANUALLY"
settingsobject(CustomerSettingsResponse)
trackingItemsArray of objects(TrackingItemCatalogueResponse)

The tracking item catalogues associated with the customer.

officeobject(InvoiceOfficeResponse)
collectionAgentIdstring(uuid)

The collection agent ID associated with the customer.

Response
application/json
{
  "id": "string",
  "externalId": "string",
  "name": "string",
  "creationTime": "2019-08-24T14:15:22Z",
  "lastUpdatedTime": "2019-08-24T14:15:22Z",
  "people": [
    { … }
  ],
  "addresses": [
    { … }
  ],
  "directDebitMandate": {
    "id": "string",
    "status": "CREATED",
    "statusReasonCode": "PENDING_DD_CAPABILITY",
    "statusReason": "string",
    "creationTime": "2019-08-24T14:15:22Z",
    "lastUpdatedTime": "2019-08-24T14:15:22Z",
    "authorisationTime": "2019-08-24T14:15:22Z",
    "submissionTime": "2019-08-24T14:15:22Z",
    "url": "string",
    "bankAccountNumber": "string",
    "personId": "string",
    "distributionTime": "2019-08-24T14:15:22Z",
    "lastNotificationSentTime": "2019-08-24T14:15:22Z"
  },
  "billerBankAccount": {
    "accountHolderAddress": { … },
    "accountHolderName": "string",
    "bankAccount": { … },
    "bankAddress": { … },
    "currencyCode": "AED"
  },
  "timezone": "string",
  "discount": {
    "percentage": 0,
    "period": 0
  },
  "externalData": [
    { … }
  ],
  "tags": [
    "string"
  ],
  "status": "ACTIVE",
  "statusReasonCode": "MERGED",
  "settings": {
    "paymentSettings": { … }
  },
  "trackingItems": [
    { … }
  ],
  "office": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "string",
    "trackingItemId": "c7c7fc03-0b17-402e-aa79-1d532a6db210",
    "details": { … }
  },
  "collectionAgentId": "fe30a7f6-c47c-4051-9601-bd9dbc464447"
}

Retrieve a customer

Request

Security
Biller Access Token (Staging) or Biller Access Token (Production)
Path
idstringnon-emptyrequired

The id of the customer to get the details for

Query
idTypestringrequired

The connector type that this ID refers to

Enum"XERO""QUICKBOOKS""ACTIONSTEP""EXTERNAL"
includeCustomerFinancialDetailsboolean

This flag determines whether the response should include the financial status of the customer's invoices and payments.

curl -i -X GET \
  'https://developer.adfin.com/_mock/products/direct-integration/direct-integration-api-reference/customers/{id}?idType=XERO&includeCustomerFinancialDetails=true' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

The customer with the specified ID.

Bodyapplication/json
idstring

The Adfin id of the customer.

externalIdstring

The id of the customer from the platform that is integrating with Adfin.

namestring

The full name of the customer.

creationTimestring(date-time)

The time the customer was created.

lastUpdatedTimestring(date-time)

The last time when the customer was updated.

peopleArray of objects(Person)

The list of people assigned to the customer.

addressesArray of objects(Address)

The list of the addresses for the customer.

directDebitMandateobject(DirectDebitMandateSummary)
billerBankAccountobject(CustomerBankAccount)
timezonestring

The timezone of the customer.

discountobject(CustomerDiscount)
externalDataArray of objects(CustomerExternalData)

References about this customer from external platforms Adfin integrates with, such as ID, etc.

tagsArray of strings

The tag ids associated with the customer.

statusstring

The status of the customer (ACTIVE, ARCHIVED)

Enum"ACTIVE""ARCHIVED"
statusReasonCodestring

The reason as a predefined code for why the customer is in a certain status

Enum"MERGED""ARCHIVED_MANUALLY"
settingsobject(CustomerSettingsResponse)
trackingItemsArray of objects(TrackingItemCatalogueResponse)

The tracking item catalogues associated with the customer.

officeobject(InvoiceOfficeResponse)
collectionAgentIdstring(uuid)

The collection agent ID associated with the customer.

Response
application/json
{
  "id": "string",
  "externalId": "string",
  "name": "string",
  "creationTime": "2019-08-24T14:15:22Z",
  "lastUpdatedTime": "2019-08-24T14:15:22Z",
  "people": [
    { … }
  ],
  "addresses": [
    { … }
  ],
  "directDebitMandate": {
    "id": "string",
    "status": "CREATED",
    "statusReasonCode": "PENDING_DD_CAPABILITY",
    "statusReason": "string",
    "creationTime": "2019-08-24T14:15:22Z",
    "lastUpdatedTime": "2019-08-24T14:15:22Z",
    "authorisationTime": "2019-08-24T14:15:22Z",
    "submissionTime": "2019-08-24T14:15:22Z",
    "url": "string",
    "bankAccountNumber": "string",
    "personId": "string",
    "distributionTime": "2019-08-24T14:15:22Z",
    "lastNotificationSentTime": "2019-08-24T14:15:22Z"
  },
  "billerBankAccount": {
    "accountHolderAddress": { … },
    "accountHolderName": "string",
    "bankAccount": { … },
    "bankAddress": { … },
    "currencyCode": "AED"
  },
  "timezone": "string",
  "discount": {
    "percentage": 0,
    "period": 0
  },
  "externalData": [
    { … }
  ],
  "tags": [
    "string"
  ],
  "status": "ACTIVE",
  "statusReasonCode": "MERGED",
  "settings": {
    "paymentSettings": { … }
  },
  "trackingItems": [
    { … }
  ],
  "office": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "string",
    "trackingItemId": "c7c7fc03-0b17-402e-aa79-1d532a6db210",
    "details": { … }
  },
  "collectionAgentId": "fe30a7f6-c47c-4051-9601-bd9dbc464447"
}

Update a customer by id

Request

Security
Biller Access Token (Staging) or Biller Access Token (Production)
Path
idstringrequired

The id of the customer to update.

Bodyapplication/jsonrequired
externalIdstring

The id of the customer from the platform that is integrating with Adfin.

namestring

The full name of the customer.

peopleArray of objects(Person)

The list of people assigned to the customer.

addressesArray of objects(Address)

The list of the addresses for the customer. Only 1 pe supported for now

externalDataobject(CustomerExternalData)
trackingItemIdsArray of strings(uuid)

The list of tracking item catalogue IDs associated with the customer.

officeIdstring(uuid)

The office ID associated with the customer.

collectionAgentIdstring(uuid)

The collection agent ID to associate with the customer.

curl -i -X PUT \
  'https://developer.adfin.com/_mock/products/direct-integration/direct-integration-api-reference/customers/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "externalId": "string",
    "name": "string",
    "people": [
      {
        "id": "string",
        "firstName": "string",
        "lastName": "string",
        "email": "string",
        "phoneNo": "string",
        "isPrimaryContact": true,
        "isIncludedInCommunications": true,
        "validForEmailCommunication": true,
        "validForPhoneCommunication": true
      }
    ],
    "addresses": [
      {
        "city": "string",
        "postalCode": "string",
        "country": "st",
        "addressLine1": "string"
      }
    ],
    "externalData": {
      "connectorType": "XERO",
      "id": "string",
      "name": "string"
    },
    "trackingItemIds": [
      "497f6eca-6276-4993-bfeb-53cbbbba6f08"
    ],
    "officeId": "da08ce10-cc2b-4a3d-a418-e10a176cc27a",
    "collectionAgentId": "fe30a7f6-c47c-4051-9601-bd9dbc464447"
  }'

Responses

The request has succeeded and has resulted in one customer being updated.

Bodyapplication/json
idstring

The Adfin id of the customer.

externalIdstring

The id of the customer from the platform that is integrating with Adfin.

namestring

The full name of the customer.

creationTimestring(date-time)

The time the customer was created.

lastUpdatedTimestring(date-time)

The last time when the customer was updated.

peopleArray of objects(Person)

The list of people assigned to the customer.

addressesArray of objects(Address)

The list of the addresses for the customer.

directDebitMandateobject(DirectDebitMandateSummary)
billerBankAccountobject(CustomerBankAccount)
timezonestring

The timezone of the customer.

discountobject(CustomerDiscount)
externalDataArray of objects(CustomerExternalData)

References about this customer from external platforms Adfin integrates with, such as ID, etc.

tagsArray of strings

The tag ids associated with the customer.

statusstring

The status of the customer (ACTIVE, ARCHIVED)

Enum"ACTIVE""ARCHIVED"
statusReasonCodestring

The reason as a predefined code for why the customer is in a certain status

Enum"MERGED""ARCHIVED_MANUALLY"
settingsobject(CustomerSettingsResponse)
trackingItemsArray of objects(TrackingItemCatalogueResponse)

The tracking item catalogues associated with the customer.

officeobject(InvoiceOfficeResponse)
collectionAgentIdstring(uuid)

The collection agent ID associated with the customer.

Response
application/json
{
  "id": "string",
  "externalId": "string",
  "name": "string",
  "creationTime": "2019-08-24T14:15:22Z",
  "lastUpdatedTime": "2019-08-24T14:15:22Z",
  "people": [
    { … }
  ],
  "addresses": [
    { … }
  ],
  "directDebitMandate": {
    "id": "string",
    "status": "CREATED",
    "statusReasonCode": "PENDING_DD_CAPABILITY",
    "statusReason": "string",
    "creationTime": "2019-08-24T14:15:22Z",
    "lastUpdatedTime": "2019-08-24T14:15:22Z",
    "authorisationTime": "2019-08-24T14:15:22Z",
    "submissionTime": "2019-08-24T14:15:22Z",
    "url": "string",
    "bankAccountNumber": "string",
    "personId": "string",
    "distributionTime": "2019-08-24T14:15:22Z",
    "lastNotificationSentTime": "2019-08-24T14:15:22Z"
  },
  "billerBankAccount": {
    "accountHolderAddress": { … },
    "accountHolderName": "string",
    "bankAccount": { … },
    "bankAddress": { … },
    "currencyCode": "AED"
  },
  "timezone": "string",
  "discount": {
    "percentage": 0,
    "period": 0
  },
  "externalData": [
    { … }
  ],
  "tags": [
    "string"
  ],
  "status": "ACTIVE",
  "statusReasonCode": "MERGED",
  "settings": {
    "paymentSettings": { … }
  },
  "trackingItems": [
    { … }
  ],
  "office": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "string",
    "trackingItemId": "c7c7fc03-0b17-402e-aa79-1d532a6db210",
    "details": { … }
  },
  "collectionAgentId": "fe30a7f6-c47c-4051-9601-bd9dbc464447"
}

Resume collection for a customer

Request

Starts collection from the customer by the named methods again. Methods that are not named keep their current state, and a method that is not paused stays as it is.

Security
Biller Access Token (Staging) or Biller Access Token (Production)
Path
customerIdstring(uuid)required

The identifier of the customer.

Bodyapplication/jsonrequired
collectionMethodsArray of stringsnon-emptyuniquerequired

The collection methods to resume. At least one method is required.

Items Enum"AUTO_COLLECT""ON_DEMAND"
curl -i -X PUT \
  'https://developer.adfin.com/_mock/products/direct-integration/direct-integration-api-reference/customers/{customerId}:resume_collection' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "collectionMethods": [
      "AUTO_COLLECT"
    ]
  }'

Responses

Collection is resumed for the named methods.

Response
No content

Pause collection for a customer

Request

Stops collection from the customer by the named methods. Payment requests already raised for the customer are not collected by those methods until collection is resumed. Methods that are not named keep collecting, and a method that is already paused stays as it is.

Security
Biller Access Token (Staging) or Biller Access Token (Production)
Path
customerIdstring(uuid)required

The identifier of the customer.

Bodyapplication/jsonrequired
collectionMethodsArray of stringsnon-emptyuniquerequired

The collection methods to pause. At least one method is required.

Items Enum"AUTO_COLLECT""ON_DEMAND"
curl -i -X PUT \
  'https://developer.adfin.com/_mock/products/direct-integration/direct-integration-api-reference/customers/{customerId}:pause_collection' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "collectionMethods": [
      "AUTO_COLLECT"
    ]
  }'

Responses

Collection is paused for the named methods.

Response
No content

Assign an owner to a customer

Request

Security
Biller Access Token (Staging) or Biller Access Token (Production)
Path
customerIdstring(uuid)required

The identifier of the customer.

Bodyapplication/jsonrequired
userIdstring(uuid)required

The id of the user to assign as the customer's owner.

curl -i -X PUT \
  'https://developer.adfin.com/_mock/products/direct-integration/direct-integration-api-reference/customers/{customerId}:assign_owner' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "userId": "2c4a230c-5085-4924-a3e1-25fb4fc5965b"
  }'

Responses

The owner was assigned to the customer.

Response
No content

Assign an action to a customer

Request

Security
Biller Access Token (Staging) or Biller Access Token (Production)
Path
customerIdstring(uuid)required

The identifier of the customer.

Bodyapplication/jsonrequired
fieldValueIdstring(uuid)required

The id of the action to assign to the customer.

curl -i -X PUT \
  'https://developer.adfin.com/_mock/products/direct-integration/direct-integration-api-reference/customers/{customerId}:assign_action' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "fieldValueId": "12e0f006-5368-4838-b121-acd0aa54a628"
  }'

Responses

The action was assigned to the customer.

Response
No content

Get the collection preferences for a customer

Request

The values in force, after the agent's settings and every override are resolved.

Security
Biller Access Token (Staging) or Biller Access Token (Production)
Path
customerIdstring(uuid)required

The identifier of the customer.

curl -i -X GET \
  'https://developer.adfin.com/_mock/products/direct-integration/direct-integration-api-reference/customers/{customerId}/collection_preferences' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

The collection method and preferences in force.

Bodyapplication/json
collectionMethodstringrequired

The collection method in force.

Enum"AUTO_COLLECT""ON_DEMAND"
preferencesobject(CollectionPreferences)required
preferences.​paymentRemindersobject(PreferenceToggle)
preferences.​mandateRemindersobject(PreferenceToggle)
preferences.​cardRemindersobject(PreferenceToggle)
preferences.​directDebitEncouragementobject(PreferenceToggle)
preferences.​statementsobject(PreferenceToggle)
preferences.​lateFeesobject(LateFeesPreference)
preferences.​partialPaymentsobject(PartialPaymentsPreference)
preferences.​surchargingobject(PreferenceToggle)
Response
application/json
{
  "collectionMethod": "AUTO_COLLECT",
  "preferences": {
    "paymentReminders": { … },
    "mandateReminders": { … },
    "cardReminders": { … },
    "directDebitEncouragement": { … },
    "statements": { … },
    "lateFees": { … },
    "partialPayments": { … },
    "surcharging": { … }
  }
}

Reset the collection preferences for a customer

Request

Clears every override, not only these settings, including any set by Adfin or in the Adfin app. To turn a single setting off, PATCH it with an enabled of false instead; a pause set with :pause_collection survives.

Security
Biller Access Token (Staging) or Biller Access Token (Production)
Path
customerIdstring(uuid)required

The identifier of the customer.

curl -i -X DELETE \
  'https://developer.adfin.com/_mock/products/direct-integration/direct-integration-api-reference/customers/{customerId}/collection_preferences' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

The overrides held against the customer are cleared. A customer that holds none is left as it is.

Response
No content

Change the collection preferences for a customer

Request

A field left out of the body is unchanged. partialPayments takes at most one of minimumAmount or minimumPercentage.

Security
Biller Access Token (Staging) or Biller Access Token (Production)
Path
customerIdstring(uuid)required

The identifier of the customer.

Bodyapplication/jsonrequired
collectionMethodstring

The collection method to use.

Enum"AUTO_COLLECT""ON_DEMAND"
preferencesobject(CollectionPreferences)
curl -i -X PATCH \
  'https://developer.adfin.com/_mock/products/direct-integration/direct-integration-api-reference/customers/{customerId}/collection_preferences' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "collectionMethod": "AUTO_COLLECT",
    "preferences": {
      "paymentReminders": {
        "enabled": true
      },
      "mandateReminders": {
        "enabled": true
      },
      "cardReminders": {
        "enabled": true
      },
      "directDebitEncouragement": {
        "enabled": true
      },
      "statements": {
        "enabled": true
      },
      "lateFees": {
        "enabled": true,
        "gracePeriodDays": 0
      },
      "partialPayments": {
        "enabled": true,
        "minimumAmount": 0,
        "minimumPercentage": 0
      },
      "surcharging": {
        "enabled": true
      }
    }
  }'

Responses

The change was applied.

Response
No content

Remove the owner from a customer

Request

Security
Biller Access Token (Staging) or Biller Access Token (Production)
Path
customerIdstring(uuid)required

The identifier of the customer.

curl -i -X DELETE \
  'https://developer.adfin.com/_mock/products/direct-integration/direct-integration-api-reference/customers/{customerId}:remove_owner' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

The owner was removed from the customer.

Response
No content

Remove the action from a customer

Request

Security
Biller Access Token (Staging) or Biller Access Token (Production)
Path
customerIdstring(uuid)required

The identifier of the customer.

curl -i -X DELETE \
  'https://developer.adfin.com/_mock/products/direct-integration/direct-integration-api-reference/customers/{customerId}:remove_action' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

The action was removed from the customer.

Response
No content

Direct debit mandates

Operations

Invoices

Operations

Recurring invoices

Operations

Payment requests

Operations

Recurring payment requests

Operations

Payments

Operations

Payouts

Operations

Tax rates

Operations

Items

Operations

Activities

What has happened to a customer, invoice, payment request or schedule.

Operations

Scheduled Activities

What is planned next for a customer or a payment request.

Operations

Webhooks

Operations

Referrals

Operations