Skip to main content

Getting Started

This guide will walk you through your first integration with the Qard API. By the end, you'll be able to collect company data automatically.

Prerequisites​

Before you begin, ensure you have:

  • A Qard API account with API credentials
  • Your API key (available in your dashboard)

Step 1: Authentication​

All API requests require authentication via an API key in the header:

curl -X GET "https://api.qardfinance.com/api/v6/profile" \
  -H "accept: application/json" \
  -H "X-API-KEY: YOUR_API_KEY"

Step 2: Enable a Provider​

Providers are data sources. The most common one is company_legal_fr which provides French company data automatically.

PUT /api/v6/providers/company_legal_fr
{
  "enable": true
}

Enable auto-connect to skip manual authentication:

PUT /api/v6/providers/company_legal_fr/settings
{
  "auto_connect": true
}

Step 3: Create a User​

A User represents the company you want to collect data about:

POST /api/v6/users/legal
{
  "name": "Example Company SAS",
  "siren": "123456789"
}

Response:

{
  "id": "d0e497f1-6052-4f0d-b876-d4e6d7cf25bc",
  "type": "LEGAL",
  "name": "Example Company SAS",
  "siren": "123456789"
}
note

Save the returned id — you'll need it for all subsequent requests.

Step 4: Create a Data Connection​

A Data Connection links a User to a Provider and specifies which data types to collect:

POST /api/v6/users/{userId}/data-connections
{
  "requested_data_types": [
    "COMPANY_PROFILE",
    "COMPANY_OFFICER",
    "BENEFICIAL_OWNER"
  ],
  "provider_name": "company_legal_fr"
}

Step 5: Trigger a Synchronization​

Launch the data collection:

POST /api/v6/users/{userId}/sync
{
  "data_types": [
    "COMPANY_PROFILE",
    "COMPANY_OFFICER",
    "BENEFICIAL_OWNER"
  ]
}

Step 6: Check Synchronization Status​

Wait for the synchronization to complete:

GET/api/v6/users/{userId}/sync/latest

Response:

[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "data_type": "COMPANY_PROFILE",
    "provider_name": "company_legal_fr",
    "status": "SUCCESS",
    "data_connection_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "requested_at": "2024-01-15 10:30:00",
    "completed_at": "2024-01-15 10:30:05"
  },
  {
    "id": "4fb96g75-6828-5673-c4gd-3d074g77bgb7",
    "data_type": "COMPANY_OFFICER",
    "provider_name": "company_legal_fr",
    "status": "SUCCESS",
    "data_connection_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "requested_at": "2024-01-15 10:30:00",
    "completed_at": "2024-01-15 10:30:07"
  }
]

Wait until all items show status: "SUCCESS" before retrieving data.

Step 7: Retrieve the Data​

Once synchronization is complete, fetch the data:

Company Profile​

GET/api/v6/users/{userId}/company-profile

Company Officers​

GET/api/v6/users/{userId}/company-officers

Beneficial Owners​

GET/api/v6/users/{userId}/beneficial-owners

Complete Example​

Here's a full workflow in JavaScript:

const QARD_API_KEY = 'your-api-key';
const BASE_URL = 'https://api.qardfinance.com/api/v6';

async function qardFetch(endpoint, options = {}) {
  const response = await fetch(`${BASE_URL}${endpoint}`, {
    ...options,
    headers: {
      'X-API-KEY': QARD_API_KEY,
      'Content-Type': 'application/json',
      ...options.headers
    }
  });
  return response.json();
}

async function collectCompanyData(siren, companyName) {
  // 1. Create the user
  const user = await qardFetch('/users/legal', {
    method: 'POST',
    body: JSON.stringify({ name: companyName, siren })
  });

  // 2. Create the data connection
  await qardFetch(`/users/${user.id}/data-connections`, {
    method: 'POST',
    body: JSON.stringify({
      requested_data_types: ['COMPANY_PROFILE', 'COMPANY_OFFICER'],
      provider_name: 'company_legal_fr'
    })
  });

  // 3. Trigger synchronization
  await qardFetch(`/users/${user.id}/sync`, {
    method: 'POST',
    body: JSON.stringify({
      data_types: ['COMPANY_PROFILE', 'COMPANY_OFFICER']
    })
  });

  // 4. Wait for completion (simplified polling)
  let syncComplete = false;
  while (!syncComplete) {
    await new Promise(r => setTimeout(r, 2000));
    const status = await qardFetch(`/users/${user.id}/sync/latest`);
    syncComplete = status.every(s => s.status === 'SUCCESS');
  }

  // 5. Retrieve data
  const [profile, officers] = await Promise.all([
    qardFetch(`/users/${user.id}/company-profile`),
    qardFetch(`/users/${user.id}/company-officers`)
  ]);

  return { userId: user.id, profile, officers };
}

// Usage
collectCompanyData('123456789', 'Example Company SAS')
  .then(data => console.log(data));

Next Steps​

Now that you've completed your first integration:

Need Help?​