Resend Commuting Survey

const options = {
  method: 'POST',
  headers: {'x-organization-id': '<x-organization-id>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    lang: '<string>',
    start_date: '<string>',
    end_date: '<string>',
    emails: {},
    exclude_responded_period: true,
    status: '<string>',
    subject: '<string>',
    deadline: '<string>',
    template_id: '<string>'
  })
};

fetch('https://api.dcycle.io/v1/employees/resend-survey', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/v1/employees/resend-survey"

payload = {
    "lang": "<string>",
    "start_date": "<string>",
    "end_date": "<string>",
    "emails": {},
    "exclude_responded_period": True,
    "status": "<string>",
    "subject": "<string>",
    "deadline": "<string>",
    "template_id": "<string>"
}
headers = {
    "x-organization-id": "<x-organization-id>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

curl --request POST \
  --url https://api.dcycle.io/v1/employees/resend-survey \
  --header 'Content-Type: application/json' \
  --header 'x-organization-id: <x-organization-id>' \
  --data '
{
  "lang": "<string>",
  "start_date": "<string>",
  "end_date": "<string>",
  "emails": {},
  "exclude_responded_period": true,
  "status": "<string>",
  "subject": "<string>",
  "deadline": "<string>",
  "template_id": "<string>"
}
'

{
  "array": {
    "id": "<string>",
    "name": {},
    "email": {},
    "organization_id": "<string>",
    "status": "<string>",
    "situation": {}
  }
}

POST

employees

resend-survey

Resend Commuting Survey

const options = {
  method: 'POST',
  headers: {'x-organization-id': '<x-organization-id>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    lang: '<string>',
    start_date: '<string>',
    end_date: '<string>',
    emails: {},
    exclude_responded_period: true,
    status: '<string>',
    subject: '<string>',
    deadline: '<string>',
    template_id: '<string>'
  })
};

fetch('https://api.dcycle.io/v1/employees/resend-survey', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/v1/employees/resend-survey"

payload = {
    "lang": "<string>",
    "start_date": "<string>",
    "end_date": "<string>",
    "emails": {},
    "exclude_responded_period": True,
    "status": "<string>",
    "subject": "<string>",
    "deadline": "<string>",
    "template_id": "<string>"
}
headers = {
    "x-organization-id": "<x-organization-id>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

curl --request POST \
  --url https://api.dcycle.io/v1/employees/resend-survey \
  --header 'Content-Type: application/json' \
  --header 'x-organization-id: <x-organization-id>' \
  --data '
{
  "lang": "<string>",
  "start_date": "<string>",
  "end_date": "<string>",
  "emails": {},
  "exclude_responded_period": true,
  "status": "<string>",
  "subject": "<string>",
  "deadline": "<string>",
  "template_id": "<string>"
}
'

{
  "array": {
    "id": "<string>",
    "name": {},
    "email": {},
    "organization_id": "<string>",
    "status": "<string>",
    "situation": {}
  }
}

← Employees API Send the commuting survey again for a reporting period — either to a list of email addresses you name, or to every active employee who has not yet answered for that period.

Do not use status to find who has not answered. The field is accepted and deprecated, and using it silently skips people who still need the reminder.status is the employee’s processing status. It flips to uploaded the first time any period of theirs is processed and never reverts. So an employee who answered last quarter and has not answered this one still reads as uploaded, and filtering on it leaves them out of the send.Use exclude_responded_period: true instead. It is period-aware — it selects active employees with no response row for the start_date/end_date you asked about — and it takes precedence over status when both are sent.

Request

Headers

string

required

UUID of the organization whose employees you are contacting.Format: UUID

string

Your API key.

Body Parameters

string

required

Language the survey is sent in.Accepted values: ar, ca, de, en, es, fr, it, pt, zh

string

required

First day of the period the survey asks about.Format: YYYY-MM-DD

string

required

Last day of that period.Format: YYYY-MM-DD

array[string]

Send to exactly these employees, by email address. When present this wins over every other selector — no “who has not answered” logic runs at all.Omit it to select recipients by rule instead.

boolean

default:"false"

When true, send only to active employees with no response for the requested period. This is the correct way to chase non-respondents.Ignored when emails is present.

string

deprecated

Deprecated. Filters by the employee’s processing status (uploaded, loading, error), which is not a valid proxy for “has not responded to this period” — see the warning above. exclude_responded_period takes precedence over it.

string

deprecated

Ignored. Accepted so existing integrations keep validating, but the email always has Dcycle’s localized subject (“Mobility survey from ”). Since 2026-10-25.

string

Date shown to the employee as the answering deadline.Format: YYYY-MM-DD

string

UUID of a survey template to use instead of the default one.Format: UUID

Recipient selection has a precedence order, and only one branch runs:

emails present → exactly those employees.
Otherwise exclude_responded_period: true → active employees with no response for the period.
Otherwise → the remaining selection, including the deprecated status filter.

Daily survey email budgets. Every send is charged to your organization, per UTC day:

At most 5,000 distinct addresses per request: more is a 422 SURVEY_SEND_TOO_MANY_RECIPIENTS.
At most 5,000 recipients per organization per day (25 on the free plan): a send that does not fit what is left today is a 429 SURVEY_EMAIL_DAILY_LIMIT_EXCEEDED and sends nothing.
One address receives the survey from your organization at most 3 times per day. Addresses past it are left out of the send (and of the response); when every address is past it the request is a 429 SURVEY_EMAIL_RECIPIENT_LIMIT_EXCEEDED.

Every 429 carries Retry-After (seconds until 00:00 UTC).

Response

Returns 202 Accepted with the employees that were selected, not with those that were actually mailed. The send happens in the background and skips anyone with no email address, so an employee can appear in this array and receive nothing. A 202 means “selection accepted”, not “delivered”.

array[object]

The employees selected by your filters. Each is a full employee object — the fields below are the ones that matter here, but the response carries every field of the employee read schema, not just these.

Show Employee Object

string

Employee UUID.

string | null

Employee name.

string | null

Email address the survey went to.

string

Organization the employee belongs to.

string

Processing status — the same field deprecated as a filter above.

string | null

Employment situation, e.g. whether the employee is terminated.

Example

# Chase everyone who has not answered for Q1
curl -X POST "https://api.dcycle.io/v1/employees/resend-survey" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-organization-id: YOUR_ORGANIZATION_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "lang": "es",
    "start_date": "2026-01-01",
    "end_date": "2026-03-31",
    "exclude_responded_period": true,
    "deadline": "2026-04-15"
  }'

import requests

HEADERS = {
    "x-api-key": "YOUR_API_KEY",
    "x-organization-id": "YOUR_ORGANIZATION_ID",
}

# Period-aware: only those with no response for this quarter
response = requests.post(
    "https://api.dcycle.io/v1/employees/resend-survey",
    headers=HEADERS,
    json={
        "lang": "es",
        "start_date": "2026-01-01",
        "end_date": "2026-03-31",
        "exclude_responded_period": True,
        "deadline": "2026-04-15",
    },
    timeout=30,
)

sent_to = response.json()
print(f"queued for {len(sent_to)} employees")

const response = await fetch(
  "https://api.dcycle.io/v1/employees/resend-survey",
  {
    method: "POST",
    headers: {
      "x-api-key": "YOUR_API_KEY",
      "x-organization-id": "YOUR_ORGANIZATION_ID",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      lang: "es",
      start_date: "2026-01-01",
      end_date: "2026-03-31",
      exclude_responded_period: true,
      deadline: "2026-04-15",
    }),
  },
);

const sentTo = await response.json();

Successful Response

Returns 202 Accepted.

[
  {
    "id": "6b2d9e41-7a83-4c50-9f27-1e5b8d3a0c94",
    "name": "Ana Ruiz",
    "email": "ana.ruiz@example.com",
    "organization_id": "a8315ef3-dd50-43f8-b7ce-d839e68d51fa",
    "status": "uploaded",
    "situation": "active"
  }
]

An empty array means nobody matched — with exclude_responded_period: true that is the good outcome: everyone has already answered.

Common Errors

422 Unprocessable Entity

Cause: lang, start_date or end_date is missing. All three are required, whichever way you select recipients.

{
  "detail": [
    {
      "loc": ["body", "lang"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Cause: lang is not one of the nine accepted values.

{
  "detail": [
    {
      "loc": ["body", "lang"],
      "msg": "value is not a valid enumeration member; permitted: 'ar', 'ca', 'de', 'en', 'es', 'fr', 'it', 'pt', 'zh'",
      "type": "type_error.enum",
      "ctx": {
        "enum_values": ["ar", "ca", "de", "en", "es", "fr", "it", "pt", "zh"]
      }
    }
  ]
}

500 Internal Server Error

Cause: One of the addresses in emails is well formed but does not belong to any employee of this organization. The lookup finds nothing and the send fails on the missing employee, so the whole request errors — no survey goes out, not even to the addresses that did match. A malformed address never gets this far: it is rejected with 422 by the email validator before any lookup happens. So nobody@example returns 422, while nobody@example.com — valid syntax, unknown person — returns 500. Check your addresses against List Employees first, and send only known ones.

Use Cases

Chase only the people who still owe you an answer

Send with exclude_responded_period: true and the period’s dates. Employees who already answered that period are excluded, and — unlike the deprecated status filter — employees who answered a previous period are still included, because they genuinely have not answered this one.

Re-send to a specific person

Pass emails with the single address. That branch skips every response check, so it works even for someone who already answered — useful when a reply was lost or the employee asks for the link again. Make sure the address belongs to an employee: a well-formed address that matches nobody fails the whole request with a 500, and nothing is sent.

List Employees

Find the employees and their status

Create Employee

Add the people who will receive the survey

Survey Templates

The templates template_id points at

Employees API

Everything the Employees API covers

​Request

​Headers

​Body Parameters

​Response

​Example

​Successful Response

​Common Errors

​422 Unprocessable Entity

​500 Internal Server Error

​Use Cases

​Chase only the people who still owe you an answer

​Re-send to a specific person

​Related Endpoints

List Employees

Create Employee

Survey Templates

Employees API

Request

Headers

Body Parameters

Response

Example

Successful Response

Common Errors

422 Unprocessable Entity

500 Internal Server Error

Use Cases

Chase only the people who still owe you an answer

Re-send to a specific person

Related Endpoints