API
Endpoints

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
 
PropertyTypeDescription
workflowIdstringIdentifies which workflow to commence for the application.
countryCodestringIdentifies the market country code to commence the application.
redirectUrlstringIdentifies the URL the applicant should be redirected to once the application is complete.
Response
{
  "id": "bits:application::4d72cbf4-070c-4b64-b8a6-86baaee34100",
  "sessionToken": "eyJhbGciOiJIUz..."
}
PropertyTypeDescription
idstringIdentifier for the created application.
sessionTokenstringAccess 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"
}
PropertyTypeDescription
applicationIdstringIdentifies 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"
}
PropertyTypeDescription
applicationIdstringIdentifies 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"
}
PropertyTypeDescription
applicationIdstringIdentifies 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"
}
PropertyTypeDescription
applicationIdstringIdentifies 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"
}
PropertyTypeDescription
applicationIdstringIdentifies 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"
}
PropertyTypeDescription
applicationIdstringIdentifies 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"
}
PropertyTypeDescription
applicationIdstringIdentifies 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"
}
PropertyTypeDescription
applicationIdstringIdentifies 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"
}
PropertyTypeDescription
applicationIdstringIdentifies 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"
}
PropertyTypeDescription
applicationIdstringIdentifies which application to fetch the information from.

Response

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