Missions

Create Mission

Creates a mission for the API key’s team.

For hourly, daily, or monthly, send rate_amount > 0; for deliverable, send deliverables instead of rate_amount. Dates: YYYY-MM-DD.

Generate a services-agreement PDF (contract_type: services_agreement, default) — use_folkyn_template: true + team_signer_id, then either:

Default template: template_locale = fr or en.
Custom template: folkyn_template_id = prestation template UUID.

Generate a master-agreement PDF (contract_type: master_agreement): master_agreement_template_id + master_agreement_valid_until + team_signer_id. If the freelancer already has a framework agreement in progress or awaiting signature (same team, not expired), that agreement is reused and linked to the mission — no new PDF is generated and template fields are ignored. Send template fields only when no current framework agreement exists (e.g. first mission under master agreement, or previous agreement expired).

For services agreements only, omit template fields to create a mission without a generated document. Master-agreement missions require either a reusable framework agreement or master_agreement_template_id / uploaded master_agreement_file. Optional: purchase_order, project_code_id, approver_id. The freelance referent is set on the freelancer profile (PATCH /api/v1/freelancers/{id}), not on mission create.

POST

https://api.folkyn.com

api

missions

curl --request POST \
  --url https://api.folkyn.com/api/v1/missions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Backend API — Q3",
  "description": "API development and maintenance for the Q3 release.",
  "mission_type": "daily",
  "contract_type": "services_agreement",
  "rate_amount": 650,
  "start_date": "2026-07-01",
  "end_date": "2026-12-31",
  "freelancer_id": "aaaaaaaa-bbbb-4ccc-dddd-eeeeeeeeeeee",
  "team_signer_id": "bbbbbbbb-cccc-4ddd-eeee-ffffffffffff",
  "use_folkyn_template": true,
  "template_locale": "fr"
}
'

{
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "description": "<string>",
    "has_document": true,
    "currency": "EUR",
    "rate_amount": 123,
    "client_rate_amount": 123,
    "start_date": "2023-12-25",
    "end_date": "2023-12-25",
    "early_termination_date": "2023-12-25",
    "terminated_by": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "external_referent": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "email": "<string>",
      "company": "<string>",
      "siren": "<string>",
      "address": "<string>",
      "postal_code": "<string>",
      "city": "<string>"
    },
    "purchase_order": "<string>",
    "external_id": "<string>",
    "project_code_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "project_code": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "external_id": "<string>"
    },
    "project_codes": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "name": "<string>",
        "external_id": "<string>"
      }
    ],
    "deliverables_catalog": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "name": "<string>",
        "quantity": 123,
        "amount_excl_vat": 123,
        "order_index": 123
      }
    ],
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "created_by": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "first_name": "<string>",
      "last_name": "<string>"
    },
    "freelancer": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "first_name": "<string>",
      "last_name": "<string>",
      "email": "<string>",
      "referent": {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "first_name": "<string>",
        "last_name": "<string>",
        "email": "<string>"
      }
    },
    "team_signer": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "first_name": "<string>",
      "last_name": "<string>"
    }
  }
}

{
  "error": {
    "code": 401,
    "message": "<string>",
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "details": {
      "field": "name",
      "requiredScope": "tags:write",
      "retryAfterSeconds": 1
    }
  }
}

{
  "error": {
    "code": 401,
    "message": "<string>",
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "details": {
      "field": "name",
      "requiredScope": "tags:write",
      "retryAfterSeconds": 1
    }
  }
}

{
  "error": {
    "code": 401,
    "message": "<string>",
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "details": {
      "field": "name",
      "requiredScope": "tags:write",
      "retryAfterSeconds": 1
    }
  }
}

{
  "error": {
    "code": 401,
    "message": "<string>",
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "details": {
      "field": "name",
      "requiredScope": "tags:write",
      "retryAfterSeconds": 1
    }
  }
}

{
  "error": {
    "code": 401,
    "message": "<string>",
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "details": {
      "field": "name",
      "requiredScope": "tags:write",
      "retryAfterSeconds": 1
    }
  }
}

Authorizations

Authorization

string

header

required

Use Authorization: Bearer <your_api_key>

Body

application/json

name

string

required

description

string

required

Mission objectives, deliverables, and working conditions.

mission_type

enum<string>

required

Billing model for the mission (Postgres enum mission_type). hourly / daily / monthly use rate_amount as the price per that unit in currency. deliverable missions bill via the deliverables catalog (quantities and line amounts); rate_amount may still be set as a reference but line totals come from catalog rows on mission detail.

Available options:

hourly,

daily,

monthly,

deliverable

start_date

string<date>

required

YYYY-MM-DD

end_date

string<date>

required

YYYY-MM-DD

freelancer_id

string<uuid>

required

Active freelancer profile UUID on the team.

contract_type

enum<string>

default:services_agreement

Available options:

services_agreement,

master_agreement

rate_amount

number

Required for hourly, daily, and monthly missions (HT unit rate). Omit for deliverable missions.

deliverables

object[]

Required when mission_type is deliverable.

Show child attributes

team_signer_id

string<uuid>

Required when generating a contract from a template (folkyn_template_id or master_agreement_template_id). Active team member profile UUID as company signatory.

purchase_order

string

project_code_id

string<uuid>

approver_id

string<uuid>

Active team-admin UUID — mission stays in draft until approved.

use_folkyn_template

boolean

Set true to generate a services-agreement PDF from a DOCX template.

template_locale

enum<string>

Default prestation template language. Use instead of folkyn_template_id when you do not have the template UUID.

Available options:

fr,

en

folkyn_template_id

string<uuid>

Prestation template UUID. Alternative to template_locale.

master_agreement_template_id

string<uuid>

Team DOCX template UUID (master_agreement only). Requires team_signer_id and master_agreement_valid_until. Ignored when the freelancer already has a current framework agreement (in progress or awaiting signature).

master_agreement_valid_until

string<date>

Framework agreement end date (YYYY-MM-DD). Required with master_agreement_template_id. Ignored when an existing framework agreement is reused.

Response

Created — same object as GET /api/v1/missions/{id}

data

object

Show child attributes

curl --request POST \
  --url https://api.folkyn.com/api/v1/missions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Backend API — Q3",
  "description": "API development and maintenance for the Q3 release.",
  "mission_type": "daily",
  "contract_type": "services_agreement",
  "rate_amount": 650,
  "start_date": "2026-07-01",
  "end_date": "2026-12-31",
  "freelancer_id": "aaaaaaaa-bbbb-4ccc-dddd-eeeeeeeeeeee",
  "team_signer_id": "bbbbbbbb-cccc-4ddd-eeee-ffffffffffff",
  "use_folkyn_template": true,
  "template_locale": "fr"
}
'

{
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "description": "<string>",
    "has_document": true,
    "currency": "EUR",
    "rate_amount": 123,
    "client_rate_amount": 123,
    "start_date": "2023-12-25",
    "end_date": "2023-12-25",
    "early_termination_date": "2023-12-25",
    "terminated_by": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "external_referent": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "email": "<string>",
      "company": "<string>",
      "siren": "<string>",
      "address": "<string>",
      "postal_code": "<string>",
      "city": "<string>"
    },
    "purchase_order": "<string>",
    "external_id": "<string>",
    "project_code_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "project_code": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "external_id": "<string>"
    },
    "project_codes": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "name": "<string>",
        "external_id": "<string>"
      }
    ],
    "deliverables_catalog": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "name": "<string>",
        "quantity": 123,
        "amount_excl_vat": 123,
        "order_index": 123
      }
    ],
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "created_by": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "first_name": "<string>",
      "last_name": "<string>"
    },
    "freelancer": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "first_name": "<string>",
      "last_name": "<string>",
      "email": "<string>",
      "referent": {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "first_name": "<string>",
        "last_name": "<string>",
        "email": "<string>"
      }
    },
    "team_signer": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "first_name": "<string>",
      "last_name": "<string>"
    }
  }
}

{
  "error": {
    "code": 401,
    "message": "<string>",
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "details": {
      "field": "name",
      "requiredScope": "tags:write",
      "retryAfterSeconds": 1
    }
  }
}

{
  "error": {
    "code": 401,
    "message": "<string>",
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "details": {
      "field": "name",
      "requiredScope": "tags:write",
      "retryAfterSeconds": 1
    }
  }
}

{
  "error": {
    "code": 401,
    "message": "<string>",
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "details": {
      "field": "name",
      "requiredScope": "tags:write",
      "retryAfterSeconds": 1
    }
  }
}

{
  "error": {
    "code": 401,
    "message": "<string>",
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "details": {
      "field": "name",
      "requiredScope": "tags:write",
      "retryAfterSeconds": 1
    }
  }
}

{
  "error": {
    "code": 401,
    "message": "<string>",
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "details": {
      "field": "name",
      "requiredScope": "tags:write",
      "retryAfterSeconds": 1
    }
  }
}

Overview

Specification

Project codes

Team tags

Teams

Missions

Freelancers

Users

Activity reports

Accounting

Create Mission

Authorizations

Body

Response