Skip to content
/
Create a customer

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 for Adfin's own integrations and system events. These tokens authenticate Adfin as the platform itself (not as a specific biller) and are required for endpoints like /api/webhook.

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

oAuth2

Operations

Biller

Operations

Customers

Operations

Retrieve a list of customers by filter

Request

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

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

searchTextstring

Fuzzy search a customer based on a text

ddMandateSignedStartTimestring

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

ddMandateSignedEndTimestring

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

ddMandateStatusesstring

The status of the latest direct debit mandate

includeCustomerFinancialDetailsstring

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

financialStatusesstring

The financial statuses of the payment situation of the customer

lastUpdatedStartTimestring

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

tagIdsstring

The tag ids of the customer

customerIdsstring

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/api-docs/prod/customers?onlyCustomersWithActivity=string&searchText=string&ddMandateSignedStartTime=string&ddMandateSignedEndTime=string&ddMandateStatuses=string&includeCustomerFinancialDetails=string&financialStatuses=string&lastUpdatedStartTime=string&tagIds=string&customerIds=string&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)

Contains pagination information for a set of results

paginationobject(Pagination)

Contains pagination information for a set of results

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

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)

References about the customer from external platforms Adfin integrates with.

curl -i -X PUT \
  https://developer.adfin.com/_mock/api-docs/prod/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
      }
    ],
    "addresses": [
      {
        "id": "string",
        "city": "string",
        "postalCode": "string",
        "country": "string",
        "addressLine1": "string"
      }
    ],
    "externalData": {
      "connectorType": "string",
      "id": "string",
      "name": "string"
    }
  }'

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)

Direct Debit details.

timezonestring

The timezone of the customer.

discountobject(CustomerDiscount)

The customer discount details.

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.

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": "string",
    "statusReasonCode": "string",
    "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"
  },
  "timezone": "string",
  "discount": {
    "percentage": 0,
    "period": 0
  },
  "externalData": [
    { … }
  ],
  "tags": [
    "string"
  ]
}

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)

References about the customer from external platforms Adfin integrates with.

curl -i -X POST \
  https://developer.adfin.com/_mock/api-docs/prod/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": "string",
      "id": "string",
      "name": "string"
    }
  }'

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)

Direct Debit details.

timezonestring

The timezone of the customer.

discountobject(CustomerDiscount)

The customer discount details.

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.

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": "string",
    "statusReasonCode": "string",
    "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"
  },
  "timezone": "string",
  "discount": {
    "percentage": 0,
    "period": 0
  },
  "externalData": [
    { … }
  ],
  "tags": [
    "string"
  ]
}

Upsert customer workflow settings

Request

Security
Biller Access Token (Staging) or Biller Access Token (Production)
Bodyapplication/jsonrequired
customerIdsArray of stringsrequired

List of customer IDs to update

workflowSettingsobject(CustomerWorkflowSettings)required

Customer workflow settings

workflowSettings.​autoCollectobject(AutoCollectSettings)required

Auto-collect workflow settings

workflowSettings.​autoCollect.​isEnabledbooleanrequired

Indicates whether auto-collect workflow is enabled

workflowSettings.​autoCollect.​isDefaultbooleanrequired

Indicates whether auto-collect is the default workflow

workflowSettings.​autoCollect.​pauseCollectionboolean

When true, payment collection is paused. While paused, no automatic retries or scheduled collection attempts will occur.

Example: true
workflowSettings.​autoCollect.​resumeCollectionAtstring(date-time)

The timestamp when automatic collection should resume. If null, collection remains paused until updated manually.

Example: "2025-01-15T10:00:00Z"
workflowSettings.​onDemandobject(OnDemandSettings)required

On-demand workflow settings

workflowSettings.​onDemand.​isEnabledbooleanrequired

Indicates whether on-demand workflow is enabled

workflowSettings.​onDemand.​isDefaultbooleanrequired

Indicates whether on-demand is the default workflow

workflowSettings.​customerStatementobject(CustomerStatementSettings)required

Customer statement workflow settings

workflowSettings.​customerStatement.​isEnabledbooleanrequired

Indicates whether customer statement workflow is enabled

curl -i -X PUT \
  https://developer.adfin.com/_mock/api-docs/prod/customers/workflow_settings \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "customerIds": [
      "string"
    ],
    "workflowSettings": {
      "autoCollect": {
        "isEnabled": true,
        "isDefault": true,
        "pauseCollection": true,
        "resumeCollectionAt": "2025-01-15T10:00:00Z"
      },
      "onDemand": {
        "isEnabled": true,
        "isDefault": true
      },
      "customerStatement": {
        "isEnabled": true
      }
    }
  }'

Responses

The customer workflow settings were successfully updated.

Bodyapplication/json
autoCollectobject(AutoCollectSettings)required

Auto-collect workflow settings

autoCollect.​isEnabledbooleanrequired

Indicates whether auto-collect workflow is enabled

autoCollect.​isDefaultbooleanrequired

Indicates whether auto-collect is the default workflow

autoCollect.​pauseCollectionboolean

When true, payment collection is paused. While paused, no automatic retries or scheduled collection attempts will occur.

Example: true
autoCollect.​resumeCollectionAtstring(date-time)

The timestamp when automatic collection should resume. If null, collection remains paused until updated manually.

Example: "2025-01-15T10:00:00Z"
onDemandobject(OnDemandSettings)required

On-demand workflow settings

onDemand.​isEnabledbooleanrequired

Indicates whether on-demand workflow is enabled

onDemand.​isDefaultbooleanrequired

Indicates whether on-demand is the default workflow

customerStatementobject(CustomerStatementSettings)required

Customer statement workflow settings

customerStatement.​isEnabledbooleanrequired

Indicates whether customer statement workflow is enabled

Response
application/json
{
  "autoCollect": {
    "isEnabled": true,
    "isDefault": true,
    "pauseCollection": true,
    "resumeCollectionAt": "2025-01-15T10:00:00Z"
  },
  "onDemand": {
    "isEnabled": true,
    "isDefault": true
  },
  "customerStatement": {
    "isEnabled": true
  }
}

Retrieve a customer

Request

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

The id of the customer to get the details for

Query
idTypestringrequired

The connector type that this ID refers to

includeCustomerFinancialDetailsstring

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/api-docs/prod/customers/{id}?idType=string&includeCustomerFinancialDetails=string' \
  -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)

Direct Debit details.

timezonestring

The timezone of the customer.

discountobject(CustomerDiscount)

The customer discount details.

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.

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": "string",
    "statusReasonCode": "string",
    "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"
  },
  "timezone": "string",
  "discount": {
    "percentage": 0,
    "period": 0
  },
  "externalData": [
    { … }
  ],
  "tags": [
    "string"
  ]
}

Retrieve customer workflow settings

Request

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

The id of the customer to get workflow settings for

curl -i -X GET \
  'https://developer.adfin.com/_mock/api-docs/prod/customers/{id}/workflow_settings' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

The workflow settings were retrieved.

Bodyapplication/json
autoCollectobject(AutoCollectSettings)required

Auto-collect workflow settings

autoCollect.​isEnabledbooleanrequired

Indicates whether auto-collect workflow is enabled

autoCollect.​isDefaultbooleanrequired

Indicates whether auto-collect is the default workflow

autoCollect.​pauseCollectionboolean

When true, payment collection is paused. While paused, no automatic retries or scheduled collection attempts will occur.

Example: true
autoCollect.​resumeCollectionAtstring(date-time)

The timestamp when automatic collection should resume. If null, collection remains paused until updated manually.

Example: "2025-01-15T10:00:00Z"
onDemandobject(OnDemandSettings)required

On-demand workflow settings

onDemand.​isEnabledbooleanrequired

Indicates whether on-demand workflow is enabled

onDemand.​isDefaultbooleanrequired

Indicates whether on-demand is the default workflow

customerStatementobject(CustomerStatementSettings)required

Customer statement workflow settings

customerStatement.​isEnabledbooleanrequired

Indicates whether customer statement workflow is enabled

Response
application/json
{
  "autoCollect": {
    "isEnabled": true,
    "isDefault": true,
    "pauseCollection": true,
    "resumeCollectionAt": "2025-01-15T10:00:00Z"
  },
  "onDemand": {
    "isEnabled": true,
    "isDefault": true
  },
  "customerStatement": {
    "isEnabled": true
  }
}

Direct debit mandates

Operations

Invoices

Operations

Recurring invoices

Operations

Payment requests

Operations

Recurring payment requests

Operations

Payments

Operations

Tax rates

Operations

Items

Operations

Workflows

Operations

Webhooks

Operations