Endpoints

ℹ️

All endpoints require a valid access token with a specific scope for access. Please read Authentication and Authorization documentation.

Versioning

The current version (v1) of the Bits API leverages URL path versioning. Future versions of the API will however switch to media type versioning. Read more about it in the chapter on API Versioning. This switch will be announced well in advance and the docs updated accordingly.

Managing Applications

Create application

POST /v1/applications.create

The endpoint creates an application on the specific workflow and market. All input parameters can be found on the "Integration" tab in a workflow on the Bits Dashboard.

The POST /v1/applications.create will return a sessionToken which is a Bearer token and is only authorized to perform actions on the application it just created. The sessionToken is used to start the no-code onboarding. The sessionToken is valid for 60 minutes.

Request

curl

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -d '{
    "workflowId": "<WORKFLOW_ID>",
    "countryCode": "<COUNTRY_CODE>",
    "redirectUrl": "<REDIRECT_URL>",
  }' \
  https://api.bits.bi/v1/applications.create

Property	Type	Description
`workflowId`	`string`	Identifies which workflow to commence for the application.
`countryCode`	`string`	Identifies the market country code to commence the application.
`redirectUrl`	`string`	Identifies the URL the applicant should be redirected to once the application is complete.

Response

{
  "id": "bits:application::4d72cbf4-070c-4b64-b8a6-86baaee34100",
  "sessionToken": "eyJhbGciOiJIUz..."
}

Property	Type	Description
`id`	`string`	Identifier for the created application.
`sessionToken`	`string`	Access token used to execute the application.

Fetch application status

POST /v1/applications.get

The endpoint returns the status of an application. The possible values are:

NOT_STARTED
IN_PROGRESS
APPROVED
DECLINED
FAILED
CANCELLED
MANUAL_REVIEW
MANUALLY_APPROVED
MANUALLY_DECLINED

Request

{
  "applicationId": "bits:application::4d72cbf4-070c-4b64-b8a6-86baaee34100"
}

Property	Type	Description
`applicationId`	`string`	Identifies which application to fetch the status from.

Response

{
  "applicationId": "bits:application::4d72cbf4-070c-4b64-b8a6-86baaee34100",
  "status": "APPROVED",
  "customerId": "bits:customer::dd02eb82-9bf5-4922-b970-9d2ed2cc0639",
  "workflowId": "bits:workflow::5edba11d-bcd1-411b-a6d4-f99ae029f9cd",
  "marketId": "bits:market::296e5995-60ce-4479-bb7c-52d4683c05a2",
  "createdAt": "2020-01-01T13:37:00Z",
  "updatedAt": "2020-01-01T13:38:00Z"
}

Organization

Fetch organization general information

POST /v1/applications.organization.get

The endpoint returns the organization information on an application.

Request

{
  "applicationId": "bits:application::4d72cbf4-070c-4b64-b8a6-86baaee34100"
}

Property	Type	Description
`applicationId`	`string`	Identifies which application to fetch the information from.

Response

{
  "organizationName": "Taraxacum AB",
  "organizationNumber": {
    "id": "55937532453",
    "issuingCountry": "SE"
  },
  "legalType": "Private Liability Company",
  "foundationDate": "2020-01-01",
  "registrationDate": "2022-04-11",
  "addresses": [
    {
      "type": "VISITING",
      "addressLine1": "Drottninggatan 32",
      "postalCode": "11145",
      "city": "Stockholm",
      "country": "SE",
      "region": "STOCKHOLM"
    },
    {
      "type": "POSTAL",
      "addressLine1": "Drottninggatan 36",
      "addressLine2": "Floor 5",
      "postalCode": "11145",
      "city": "STOCKHOLM",
      "country": "SE",
      "region": "STOCKHOLM"
    }
  ],
  "visitAddress": { // Deprecated. Use the field "addresses" instead.
    "addressLine1": "Drottninggatan 32",
    "postalCode": "11145",
    "city": "Stockholm",
    "country": "SE",
    "region": "STOCKHOLM"
  },
  "postalAddress": { // Deprecated. Use the field "addresses" instead.
    "addressLine1": "Drottninggatan 36",
    "addressLine2": "Floor 5",
    "postalCode": "11145",
    "city": "STOCKHOLM",
    "country": "SE",
    "region": "STOCKHOLM"
  },
  "companyStatus": "Aktivt",
  "numberOfEmployeesInterval": "10-19 anställda",
  "industryCode": "62010", // Deprecated. Use the field "industryCodes" instead.
  "industryCodes": ["62010"],
  "businessActivity": "Programvaruproducenter",
  "registrationAuthority": {
    "authority": "BOLAGSVERKET",
    "country": "SE"
  },
  "registeredCorporateTaxDate": "2022-07-27",
  "registeredCorporateVatDate": "2022-07-01",
  "sanctionHits": [{
    "name": "Taraxacum AB",
    "aliases": ["Dandelion AB", "Taraxacum"],
    "connectedCountries": ["SE", "NO"],
    "website": "http://taraxacum.se",
    "address": {
      "type": "VISITING",
      "addressLine1": "Drottninggatan 32",
      "addressLine2": "Floor 5",
      "postalCode": "11145",
      "city": "Stockholm",
      "region": "STOCKHOLM",
      "country": "SE"
    },
    "source": {
      "name": "EU",
      "link": "http://eu.eu"
    },
    "listedDate": "1990-01-10"
  }]
}

Fetch org contact details

POST /v1/applications.organization.contactDetails.get

The endpoint returns the organization contact details on an application.

Request

{
  "applicationId": "bits:application::4d72cbf4-070c-4b64-b8a6-86baaee34100"
}

Property	Type	Description
`applicationId`	`string`	Identifies which application to fetch the information from.

Response

{
  "firstName": "Lois",
  "lastName": "Lane",
  "email": "lois.lane@metropolis.com",
  "phoneNumber": "+46701234567"
}

Fetch signing combinations

POST /v1/applications.organization.signingCombinations.get

The endpoint will return the signing combinations for an organization on an application.

Request

{
  "applicationId": "bits:application::4d72cbf4-070c-4b64-b8a6-86baaee34100"
}

Property	Type	Description
`applicationId`	`string`	Identifies which application to fetch the information from.

Response

{
  "data": [
    [
      {
        "type": "PERSON",
        "name": "Kentsson, Kenta",
        "roles": ["Ledamot"],
        "personalIdentityNumber": {
          "id": "191212121212",
          "issuingCountry": "SE"
        },
        "hasAdminRights": true,
        "sanctionHits": [
          {
            "name": "Kentsson, Kenta",
            "akas": ["Mr. Kent"],
            "gender": "Male",
            "dateOfBirths": ["1912-12-12"],
            "citizenships": ["SE"],
            "legalBasis": "terrorist",
            "source": {
              "name": "EU",
              "link": "http://eu.eu"
            },
            "listedDate": "1990-01-10"
          }
        ]
      }
    ],
    [
      {
        "type": "PERSON",
        "name": "Testsson, Ola Per",
        "roles": ["Ledamot", "Ordförande"],
        "personalIdentityNumber": {
          "id": "19721111114321",
          "issuingCountry": "SE"
        },
        "hasAdminRights": false,
        "pepHits": [
          {
            "name": "Testsson, Ola Per",
            "personalIdentityNumber": {
              "id": "197803111934",
              "issuingCountry": "SE"
            },
            "dateOfBirth": "1978-03-11",
            "gender": "Male",
            "pepCountry": "SE",
            "roles": [
              {
                "active": true,
                "category": "Politician or government official",
                "detailedCategory": "Head of State",
                "description": "President of the United States",
                "fromDate": "2017-01-20",
                "toDate": "2021-01-20"
              }
            ],
            "source": {
              "name": "some-source",
              "link": "http://test.testy"
            }
          }
        ]
      },
      {
        "type": "PERSON",
        "name": "Lantzio, Lorentz",
        "roles": ["Ledamot"],
        "personalIdentityNumber": {
          "id": "198212121212",
          "issuingCountry": "SE"
        },
        "hasAdminRights": false
      }
    ]
  ]
}

Fetch signed by

POST /v1/applications.organization.signedBy.get

The endpoint will return the person who signed the application. Normally this might be the person who performed the onboarding on behalf of the organization.

Request

{
  "applicationId": "bits:application::4d72cbf4-070c-4b64-b8a6-86baaee34100"
}

Property	Type	Description
`applicationId`	`string`	Identifies which application to fetch the information from.

Response

{
  "data": [
    {
      "name": "Clark Kent",
      "personalIdentityNumber": {
        "id": "197803111934",
        "issuingCountry": "SE"
      },
      "pepHits": [
        {
          "name": "Clark Kent",
          "personalIdentityNumber": {
            "id": "197803111934",
            "issuingCountry": "SE"
          },
          "dateOfBirth": "1978-03-11",
          "gender": "Male",
          "pepCountry": "SE",
          "roles": [
            {
              "active": true,
              "category": "Politician or government official",
              "detailedCategory": "Head of State",
              "description": "President of the United States",
              "fromDate": "2017-01-20",
              "toDate": "2021-01-20"
            }
          ],
          "source": {
            "name": "some-source",
            "link": "http://test.testy"
          }
        }
      ],
      "sanctionHits": [
        {
          "name": "Clark Kent",
          "akas": ["Superman", "Mr. Kent"],
          "gender": "Male",
          "dateOfBirths": ["1978-03-11"],
          "citizenships": ["SE"],
          "legalBasis": "terrorist",
          "source": {
            "name": "EU",
            "link": "http://eu.eu"
          },
          "listedDate": "1990-01-10"
        }
      ]
    }
  ]
}

Fetch board members

POST /v1/applications.organization.boardMembers.get

The endpoint will return the board members for an organization on an application.

Request

{
  "applicationId": "bits:application::4d72cbf4-070c-4b64-b8a6-86baaee34100"
}

Property	Type	Description
`applicationId`	`string`	Identifies which application to fetch the information from.

Response

{
  "data": [
    [
      {
        "type": "ORGANIZATION",
        "name": "ACM 2001 AB",
        "roles": ["Bolagsman"],
        "organizationIdentifier": {
          "id": "5560572850",
          "issuingCountry": "SE"
        },
        "sanctionHits": [{
          "name": "ACM 2001 AB",
          "aliases": ["ACM 2001"],
          "connectedCountries": ["SE", "NO"],
          "website": "http://acm.se",
          "address": {
            "type": "VISITING",
            "addressLine1": "Drottninggatan 32",
            "addressLine2": "Floor 5",
            "postalCode": "11145",
            "city": "Stockholm",
            "region": "STOCKHOLM",
            "country": "SE"
          },
          "source": {
            "name": "EU",
            "link": "http://eu.eu"
          },
          "listedDate": "1990-01-10"
        }]
      },
      {
        "type": "ORGANIZATION",
        "name": "Swedec AB",
        "roles": ["Bolagsman"],
        "organizationIdentifier": {
          "id": "5567164818",
          "issuingCountry": "SE"
        }
      }
    ],
    [
      {
        "type": "PERSON",
        "name": "Clark Kent",
        "roles": ["Ledamot"],
        "personalIdentityNumber": {
          "id": "197601030029",
          "issuingCountry": "SE"
        },
        "sanctionHits": [
          {
            "name": "Clark Kent",
            "akas": ["Superman", "Mr. Kent"],
            "gender": "Male",
            "dateOfBirths": ["1978-03-11"],
            "citizenships": ["SE"],
            "legalBasis": "terrorist",
            "source": {
              "name": "EU",
              "link": "http://eu.eu"
            },
            "listedDate": "1990-01-10"
          }
        ]
      },
      {
        "type": "PERSON",
        "name": "Lois Lane",
        "roles": ["Ledamot"],
        "organizationIdentifier": {
          "id": "198207140029",
          "issuingCountry": "SE"
        },
        "pepHits": [
          {
            "name": "Lois Lane",
            "personalIdentityNumber": {
              "id": "197803111934",
              "issuingCountry": "SE"
            },
            "dateOfBirth": "1978-03-11",
            "gender": "Female",
            "pepCountry": "SE",
            "roles": [
              {
                "active": true,
                "category": "Politician or government official",
                "detailedCategory": "Head of State",
                "description": "President of the United States",
                "fromDate": "2017-01-20",
                "toDate": "2021-01-20"
              }
            ],
            "source": {
              "name": "some-source",
              "link": "http://test.testy"
            }
          }
        ]
      }
    ]
  ]
}

Person

POST /v1/applications.person.get

Fetch person data

The endpoint will return information on the person related to an application. For KYC that would correspond to the applicant or onboarded customer. While for KYB it could be the person who performed the auth or IDV step while onboarding the organization.

The following fields are possibly null, if not collected: dateOfBirth, personalIdentityNumber, coordinationNumber, address.

Request

{
  "applicationId": "bits:application::4d72cbf4-070c-4b64-b8a6-86baaee34100"
}

Property	Type	Description
`applicationId`	`string`	Identifies which application to fetch the information from.

Response

{
  "firstName": "Lois",
  "lastName": "Lane",
  "email": "lois.lane@dailyplanet.com",
  "phoneNumber": "+46701234567",
  "personalIdentityNumber": {
    "id": "197803111934",
    "issuingCountry": "SE"
  },
  "dateOfBirth": "1978-03-11",
  "coordinationNumber": {
    "id": "199001629999",
    "issuingCountry": "SE"
  },
  "address": {
    "addressLine1": "Drottninggatan 32",
    "addressLine2": "lgh 123",
    "postalCode": "11145",
    "city": "Stockholm",
    "country": "SE",
    "region": "STOCKHOLM"
  },
  "pepHits": [
    {
      "name": "Lois Lane",
      "personalIdentityNumber": {
        "id": "197803111934",
        "issuingCountry": "SE"
      },
      "dateOfBirth": "1978-03-11",
      "gender": "Female",
      "pepCountry": "SE",
      "roles": [
        {
          "active": true,
          "category": "Politician or government official",
          "detailedCategory": "Head of State",
          "description": "President of the United States",
          "fromDate": "2017-01-20",
          "toDate": "2021-01-20"
        }
      ],
      "source": {
        "name": "some-source",
        "link": "http://test.testy"
      }
    }
  ],
  "sanctionHits": [
    {
      "name": "Lois Lane",
      "akas": ["Red Tornado", "Mrs. Lane"],
      "gender": "Female",
      "dateOfBirths": ["1978-03-11"],
      "citizenships": ["SE"],
      "legalBasis": "terrorist",
      "source": {
        "name": "EU",
        "link": "http://eu.eu"
      },
      "listedDate": "1990-01-10"
    }
  ]
}

Fetch person contact details

💡

Deprecated. Email and phone number are available on the get person api

POST /v1/applications.person.contactDetails.get

The endpoint returns the person contact details on an application.

Request

{
  "applicationId": "bits:application::4d72cbf4-070c-4b64-b8a6-86baaee34100"
}

Property	Type	Description
`applicationId`	`string`	Identifies which application to fetch the information from.

Response

{
  "email": "lois.lane@metropolis.com",
  "phoneNumber": "+46701234567"
}

List documents uploaded on an application

POST /applications.documents.list

The endpoint lists all documents connected with an application. The value ofdownloadURL in the response body can be used to download the document with a GET request.

The field uploadedBy can have the following values:

APPLICANT - The document was uploaded by the applicant of an application.
CUSTOMER_USER - The document was uploaded by a user via Bits Dashboard.

Request

{
  "applicationId": "bits:application::4d72cbf4-070c-4b64-b8a6-86baaee34100"
}

Property	Type	Description
`applicationId`	`string`	Identifies which application to fetch the information from.

Response

{
  "data": [
    {
      "id": "01HV12PKQR448KSA9PBV1RNX8B",
      "name": "test-document-name",
      "type": "PASSPORT",
      "context": "DOCUMENT_FRONT",
      "contentType": "test-document-content-type",
      "size": 1337,
      "createdAt": "2020-01-01T13:37:00Z",
      "downloadUrl": "https://test.com/document",
      "uploadedBy": "APPLICANT"
    }
  ]
}

List bank accounts on an application

POST /applications.bankAccounts.list

The endpoint lists all bank accounts connected with an application.

The field type can have the following values:

SWEDEN_DOMESTIC - Represents a Swedish bank account. It contains a clearing number (4-5 characters) and an account number (kontonummer, 5-11 characters).
IBAN - Represents an international bank account number. It contains a string (up to 34 characters).

Request

{
  "applicationId": "bits:application::4d72cbf4-070c-4b64-b8a6-86baaee34100"
}

Property	Type	Description
`applicationId`	`string`	Identifies which application to fetch the information from.

Response

{
  "data": [
    {
      "type": "SWEDEN_DOMESTIC",
      "clearingNumber": "12345",
      "accountNumber": "1234567890"
    },
    {
      "type": "IBAN",
      "bic": "NDEASESS",
      "iban": "SE3550000000054910000003"
    }
  ]
}

Versioning Webhook Events