openapi: 3.0.3
info:
title: API Engagement
version: "2.0"
description: |
API partenaires pour la diffusion et le suivi de missions bénévoles et civiques.
## Authentification
Tous les endpoints nécessitent une clé API transmise dans le header "x-api-key".
## Versions
- **v0** : endpoints de lecture (recherche de missions, organisations, partenaires diffuseurs)
- **v2** : endpoints d'écriture CRUD (création/modification/suppression de missions, suivi des activités)
license:
name: MIT
servers:
- url: https://api.api-engagement.beta.gouv.fr
description: Production
- url: https://api.bac-a-sable.api-engagement.beta.gouv.fr
description: Bac à sable
- url: http://localhost:3002
description: Développement local
security:
- ApiKeyAuth: []
tags:
- name: Missions
x-page-icon: bullseye
x-page-description: Recherche et consultation des missions bénévoles (v0) et gestion CRUD pour les annonceurs (v2).
description: Recherche et gestion des missions bénévoles
- name: Mes missions
x-page-icon: list-check
x-page-description: Consultation des missions que votre organisation a publiées, avec leurs statistiques d'engagement.
description: Consultation des missions publiées par votre organisation
- name: Activités
x-page-icon: chart-line
x-page-description: Déclarez et suivez les événements d'engagement générés depuis vos diffusions (candidatures, créations de compte).
description: Suivi des événements d'engagement (candidatures, créations de compte)
- name: Organisations
x-page-icon: building
x-page-description: Consultez et mettez à jour le profil de votre organisation sur la plateforme.
description: Recherche et gestion de la diffusion par organisation
- name: Partenaires
x-page-icon: handshake
x-page-description: Liste des partenaires diffuseurs disponibles sur la plateforme API Engagement.
description: Liste des partenaires diffuseurs
- name: Règles de diffusion
x-page-icon: filter
x-page-description: Configurez, en tant qu'annonceur, les règles qui déterminent quelles missions sont diffusées vers chacun de vos partenaires diffuseurs.
description: Gestion des règles de diffusion des missions vers les diffuseurs
# ──────────────────────────────────────────────────────────────────────────────
# Components
# ──────────────────────────────────────────────────────────────────────────────
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: Clé API fournie par l'équipe API Engagement
schemas:
# ── Adresse ────────────────────────────────────────────────────────────────
Address:
type: object
description: Adresse géographique d'une mission
properties:
street:
type: string
nullable: true
description: Numéro et nom de rue
example: "12 rue de la Paix"
postalCode:
type: string
nullable: true
description: Code postal
example: "75001"
city:
type: string
nullable: true
description: Ville
example: "Paris"
departmentCode:
type: string
nullable: true
description: Code du département (ex. 75, 69, 2A)
example: "75"
departmentName:
type: string
nullable: true
description: Nom du département
example: "Paris"
region:
type: string
nullable: true
description: Nom de la région
example: "Île-de-France"
country:
type: string
nullable: true
description: Pays (code ISO 3166-1 alpha-2 ou nom)
example: "France"
# ── Mission (réponse v2) ───────────────────────────────────────────────────
Mission:
type: object
description: Mission bénévole ou civique
example:
id: "64a1b2c3d4e5f6789abc0001"
clientId: "mission-bénévolat-2024-001"
publisherId: "5f5931496c7ea514150a818f"
statusCode: "ACCEPTED"
title: "Animateur bénévole en maison de retraite"
applicationUrl: "https://example.org/missions/001/postuler"
domain: "sante"
activities: ["animation", "accompagnement"]
audience: ["seniors", "personnes-isolees"]
remote: "no"
schedule: "2 heures par semaine le samedi matin"
places: 5
openToMinors: false
reducedMobilityAccessible: true
addresses:
- street: "12 rue de la Paix"
zip: "75001"
city: "Paris"
department: "75"
departmentName: "Paris"
region: "Île-de-France"
country: "France"
location:
lat: 48.8698
lon: 2.3303
organizationName: "Croix-Rouge française"
organizationRNA: "W751206979"
organizationSiren: "775672272"
organizationSiret: "77567227221138"
organizationUrl: "https://www.croix-rouge.fr"
createdAt: "2024-01-15T09:00:00.000Z"
updatedAt: "2024-03-01T14:30:00.000Z"
properties:
id:
type: string
description: Identifiant interne de la mission
example: "64a1b2c3d4e5f6789abc0001"
clientId:
type: string
description: Identifiant unique de la mission dans votre système d'information (immuable)
example: "mission-2024-001"
publisherId:
type: string
description: Identifiant du partenaire annonceur
example: "5f5931496c7ea514150a818f"
statusCode:
type: string
enum: [ACCEPTED, REFUSED, PENDING, ONGOING]
description: Statut de modération JeVeuxAider
example: "ACCEPTED"
statusComment:
type: string
nullable: true
description: Commentaire associé au statut de modération
title:
type: string
description: Titre de la mission
example: "Animateur bénévole en maison de retraite"
description:
type: string
description: |
Description complète de la mission. Texte brut ou HTML acceptés.
La valeur fournie est conservée pour le rendu riche. Si du HTML est fourni, elle est aussi convertie en texte brut pour les usages internes, la recherche et la modération.
**Recommandations** :
- Utiliser le format HTML pour une meilleure lisibilité lors de la diffusion (sauts de ligne, gras, listes)
- Structurer en plusieurs sections pour agréger des informations provenant de champs différents dans votre système
- La description est limitée à 20 000 caractères
example: "EN QUELQUES MOTS
Favoriser la mixité au sein du club
VOTRE MISSION DE SERVICE CIVIQUE
Objectifs
- Développer la féminisation et favoriser l'accès à la pratique du football des jeunes filles
Actions
- Accompagner les éducateurs dans le projet éducatif féminin
- Mettre en place des actions en faveur de la mixité
- Sensibiliser les jeunes filles éloignées de la pratique sportive
"
applicationUrl:
type: string
nullable: true
format: uri
description: URL de la page où l'utilisateur sera redirigé pour candidater (URL de la page présentant la mission)
example: "https://www.example.org/missions/animateur-maison-retraite"
image:
type: string
nullable: true
format: uri
description: URL de l'image de la mission. Si absent, l'API Engagement utilise une image de sa bibliothèque selon le domaine.
metadata:
type: string
nullable: true
description: Métadonnées libres associées à la mission.
domain:
type: string
nullable: true
description: |
Domaine d'action de la mission. Valeurs possibles :
`animaux`, `autre`, `batiment-industrie-logistique`, `benevolat-competences`, `communication`, `culture-loisirs`, `education`, `emploi`, `environnement`, `gestion-finance-droit`, `humanitaire`, `memoire-et-citoyennete`, `numerique`, `prevention-protection`, `recherche`, `sante`, `service-public-defense-securite`, `sport`, `solidarite-insertion`, `vivre-ensemble`.
> Une demande d'ajout de valeur peut être faite auprès de l'équipe API Engagement.
example: "sante"
activities:
type: array
items:
type: string
description: |
Activité(s) principale(s) de la mission. Valeurs possibles :
`accueil-de-public`, `aide-psychologique`, `activites-manuelles`, `alphabetisation`, `animation`, `Animation, Valorisation`, `art`, `autre`, `bricolage`, `collecte`, `communication`, `comptabilite-finance`, `conseil`, `distribution`, `documentation-traduction`, `ecoute-permanence`, `encadrement-d-equipes`, `enseignement-formation`, `gestion-de-projets`, `gestion-recherche-des-partenariats`, `informatique`, `jardinage`, `juridique`, `logistique`, `lutte-contre-isolement`, `Médiation, Information`, `mentorat-parrainage`, `mission-internationale`, `Préservation, Patrimoine`, `Prévention, Sensibilisation`, `ramassage-dechets`, `recrutement`, `responsabilites-associatives`, `sante-soins`, `Secours, Aide`, `secourisme`, `sensibilisation`, `soins-animaux`, `Soutien, Accompagnement`, `soutien-scolaire`, `sport`, `taches-administratives`, `Transmission, Pédagogie`, `visites`, `operations-militaires`, `sciences-humaines-social`, `restauration-hotellerie`, `maintenance-technique`, `gestion-ressources-humaines`, `gestion-entretien-patrimoine`.
> Une demande d'ajout de valeur peut être faite auprès de l'équipe API Engagement.
example: ["animation", "lutte-contre-isolement"]
tags:
type: array
items:
type: string
description: |
Mots-clés personnalisés pour taguer la mission. Chaque élément du tableau est un tag distinct.
example: ["Ecologie", "Sport", "Solidarité"]
audience:
type: array
items:
type: string
description: |
Les bénéficiaires de la mission — à qui la mission s'adresse, le public auquel sera confronté la personne qui s'engage.
example: ["Tous publics"]
requirements:
type: array
items:
type: string
description: Pré-requis relatifs à la mission.
example: ["Niveau d'étude : BAC+2", "Connaissance de langue anglaise"]
softSkills:
type: array
items:
type: string
description: |
Les compétences générales requises pour la mission. Ce champ ne repose pas sur un référentiel de compétence structuré.
example: ["Écoute active", "Communication orale"]
romeSkills:
type: array
items:
type: string
description: |
Code OGR Macro du ROME 4.0. Ce champ repose sur le référentiel "Arborescence simplifiée des compétences" (section "Arborescence du ROME").
example: ["300412", "300361"]
remote:
type: string
nullable: true
enum: [no, possible, full, local, null]
description: "Politique de télétravail. Valeurs possibles : `no` (présentiel uniquement), `possible` (distanciel possible), `full` (100% distanciel), `local` (sur site, à proximité)"
example: "no"
schedule:
type: string
nullable: true
description: Rythme de la mission (texte libre)
example: "2 heures par semaine"
startAt:
type: string
nullable: true
format: date-time
description: "Date de début de la mission souhaitée. Format ISO 8601. Défaut : now()"
example: "2024-09-01T00:00:00.000Z"
endAt:
type: string
nullable: true
format: date-time
description: "Date de fin de la mission souhaitée. Format ISO 8601. Défaut : now()"
example: "2025-06-30T00:00:00.000Z"
postedAt:
type: string
nullable: true
format: date-time
description: "Date de première publication de la mission. Format ISO 8601."
example: "2024-06-15T09:00:00.000Z"
places:
type: integer
nullable: true
minimum: 1
default: 1
description: |
Nombre de places disponibles pour la mission. Ce nombre doit être mis à jour dès qu'il évolue dans votre système afin que l'API Engagement dispose toujours de la donnée la plus récente.
example: 5
compensationAmount:
type: number
nullable: true
description: Montant minimum de l'indemnisation perçue par le bénévole ou le volontaire. Utilisé seul ou comme borne basse d'une fourchette avec `compensationAmountMax`.
example: 0
compensationAmountMax:
type: number
nullable: true
description: Montant maximum de l'indemnisation. Si renseigné, `compensationAmount` est la borne basse et `compensationAmountMax` la borne haute (ex. 0–13 €/h). Doit être supérieur ou égal à `compensationAmount`.
example: 13
compensationUnit:
type: string
nullable: true
enum: [hour, day, month, year, null]
description: "Période de l'indemnisation pour le montant fourni. Valeurs possibles : `year`, `month`, `day`, `hour`"
compensationType:
type: string
nullable: true
enum: [gross, net, null]
description: "Type d'indemnisation. Valeurs possibles : `gross` (brut), `net` (net)"
addresses:
type: array
items:
$ref: "#/components/schemas/Address"
description: |
Ensemble des localisations où se déroule la mission. Si la mission se tient dans plusieurs lieux, renseignez autant d'objets que de localisations. Pour une mission en lieu unique, le tableau ne contient qu'un seul objet.
example:
- street: "12 rue de la Paix"
postalCode: "75001"
city: "Paris"
departmentCode: "75"
departmentName: "Paris"
region: "Île-de-France"
country: "France"
type:
type: string
nullable: true
enum: [benevolat, volontariat_service_civique, volontariat_sapeurs_pompiers, volontariat_reserve_operationnelle, null]
description: Type de mission d'engagement
organizationClientId:
type: string
nullable: true
description: Identifiant de l'organisation dans votre système. L'organisation désigne l'entité qui accueille le bénévole ou le volontaire.
organizationName:
type: string
nullable: true
description: "Nom de l'organisation. Requis si un autre champ `organization*` est renseigné."
example: "Croix-Rouge française"
organizationDescription:
type: string
nullable: true
description: Description de l'organisation.
organizationUrl:
type: string
nullable: true
format: uri
description: Lien de l'organisation (ex. page de présentation sur votre site).
organizationType:
type: string
nullable: true
description: Type de l'organisation.
example: "Association déclarée"
organizationLogo:
type: string
nullable: true
format: uri
description: URL de l'image de l'organisation.
organizationRNA:
type: string
nullable: true
description: Numéro RNA de l'organisation. Uniquement valable pour les organisations de type association.
example: "W353002476"
organizationSiren:
type: string
nullable: true
description: SIREN de l'organisation.
example: "339863417"
organizationSiret:
type: string
nullable: true
description: SIRET de l'organisation.
example: "33986341700418"
organizationFullAddress:
type: string
nullable: true
description: Adresse de l'organisation. Pas de format strict attendu (contrairement à l'adresse de la mission).
organizationPostCode:
type: string
nullable: true
description: Code postal de l'organisation.
example: "94170"
organizationCity:
type: string
nullable: true
description: Ville de l'organisation.
example: "Le Perreux-sur-Marne"
organizationStatusJuridique:
type: string
nullable: true
description: Statut juridique de l'organisation.
organizationBeneficiaries:
type: array
items:
type: string
nullable: true
description: Bénéficiaires de l'organisation.
organizationActions:
type: array
items:
type: string
nullable: true
description: Principales actions menées par l'organisation.
example: ["Animation", "Valorisation", "Préservation"]
organizationReseaux:
type: array
items:
type: string
nullable: true
description: Réseau de l'organisation. Ce champ sert à renseigner les organisations ayant des antennes locales et dépendant d'un réseau national.
createdAt:
type: string
format: date-time
description: Date de création
updatedAt:
type: string
format: date-time
description: Date de dernière modification
deletedAt:
type: string
nullable: true
format: date-time
description: Date de suppression (soft delete)
# ── Mission (réponse v2 — avec champs booléens) ────────────────────────────
MissionV2:
description: Mission bénévole ou civique (format v2, étend Mission)
allOf:
- $ref: "#/components/schemas/Mission"
- type: object
properties:
openToMinors:
type: boolean
nullable: true
description: Mission ouverte aux mineurs.
reducedMobilityAccessible:
type: boolean
nullable: true
description: Mission accessible aux personnes à mobilité réduite.
closeToTransport:
type: boolean
nullable: true
description: Mission proche des transports en commun.
# ── Mission (réponse v0 — format legacy) ──────────────────────────────────
MissionLegacy:
allOf:
- $ref: "#/components/schemas/Mission"
- type: object
description: |
Mission au format legacy (v0). Quelques différences par rapport au format v2 :
- "openToMinors" et "reducedMobilityAccessible" sont retournés comme chaînes ""true"" / ""false""
- Champs supplémentaires : "_id", "activity" (concaténation), "domainLogo", "publisherName", "publisherUrl", "publisherLogo", "postedAt", "duration", "metadata"
- Champ de modération JVA : "moderation_5f5931496c7ea514150a818f_status", "moderation_5f5931496c7ea514150a818f_comment"
properties:
_id:
type: string
description: Alias de "id" (compatibilité legacy)
openToMinors:
type: string
nullable: true
enum: ["yes", "no", null]
description: Ouvert aux mineurs (format string legacy)
reducedMobilityAccessible:
type: string
nullable: true
enum: ["yes", "no", null]
description: Accessible PMR (format string legacy)
activity:
type: string
nullable: true
description: Activités concaténées en une chaîne
publisherName:
type: string
description: Nom du partenaire diffuseur
publisherUrl:
type: string
format: uri
description: URL du partenaire diffuseur
publisherLogo:
type: string
format: uri
description: Logo du partenaire diffuseur
domainLogo:
type: string
nullable: true
format: uri
description: Logo du domaine d'action
postedAt:
type: string
nullable: true
format: date-time
description: Date de première publication
duration:
type: integer
nullable: true
description: Durée de la mission en heures
location:
type: object
nullable: true
description: Coordonnées géographiques
properties:
lat:
type: number
format: double
lon:
type: number
format: double
# ── Statistiques d'une mission ────────────────────────────────────────────
MissionStatsBucket:
type: object
description: Bucket de statistiques par partenaire diffuseur
properties:
key:
type: string
description: Identifiant du partenaire diffuseur
example: "5f5931496c7ea514150a818f"
name:
type: string
nullable: true
description: Nom du partenaire diffuseur
example: "JeVeuxAider.gouv.fr"
doc_count:
type: integer
description: Nombre d'événements
example: 42
MissionStats:
type: object
description: Statistiques d'engagement pour une mission, agrégées par partenaire diffuseur
properties:
clicks:
type: array
description: Clics vers la mission, par partenaire diffuseur
items:
$ref: "#/components/schemas/MissionStatsBucket"
applications:
type: array
description: Candidatures enregistrées, par partenaire diffuseur
items:
$ref: "#/components/schemas/MissionStatsBucket"
# ── Activité ──────────────────────────────────────────────────────────────
Activity:
type: object
description: Événement d'engagement (candidature ou création de compte)
example:
_id: "64a1b2c3d4e5f6789abc0099"
type: "apply"
status: "PENDING"
clickId: "64a1b2c3d4e5f6789abc0050"
missionClientId: "mission-bénévolat-2024-001"
missionId: "64a1b2c3d4e5f6789abc0001"
tag: "homepage"
createdAt: "2024-03-15T10:22:00.000Z"
properties:
_id:
type: string
description: Identifiant de l'activité
example: "64a1b2c3d4e5f6789abc0099"
type:
type: string
enum: [apply, account]
description: Type d'événement
example: "apply"
status:
type: string
enum: [PENDING, VALIDATED, CANCELED, REFUSED, CARRIED_OUT]
description: Statut de la candidature
example: "PENDING"
clickId:
type: string
nullable: true
description: Identifiant du clic d'origine
missionClientId:
type: string
nullable: true
description: Identifiant client de la mission concernée
missionId:
type: string
nullable: true
description: Identifiant interne de la mission
tag:
type: string
nullable: true
description: Tag libre associé à l'événement
createdAt:
type: string
format: date-time
description: Date de création
# ── Organisation ──────────────────────────────────────────────────────────
Organization:
type: object
description: Organisation associative ou structure porteuse de missions
example:
_id: "64a1b2c3d4e5f6789abc0010"
title: "Croix-Rouge française"
rna: "W751206979"
siret: "77567227221138"
status: "Association loi 1901"
properties:
_id:
type: string
description: Identifiant interne
example: "64a1b2c3d4e5f6789abc0010"
title:
type: string
description: Nom de l'organisation
example: "Croix-Rouge française"
rna:
type: string
nullable: true
description: Numéro RNA (Répertoire National des Associations)
example: "W751206979"
siret:
type: string
nullable: true
description: Numéro SIRET
example: "77567227221138"
status:
type: string
nullable: true
description: Forme juridique
example: "Association loi 1901"
# ── Partenaire diffuseur ───────────────────────────────────────────────────
Partner:
type: object
description: Partenaire diffuseur de missions
example:
_id: "5f5931496c7ea514150a818f"
name: "JeVeuxAider.gouv.fr"
category: "Plateforme gouvernementale"
url: "https://www.jeveuxaider.gouv.fr"
description: "La plateforme officielle du bénévolat en France"
widget: true
api: true
campaign: false
annonceur: false
properties:
_id:
type: string
description: Identifiant du partenaire
example: "5f5931496c7ea514150a818f"
name:
type: string
description: Nom du partenaire
example: "JeVeuxAider.gouv.fr"
category:
type: string
nullable: true
description: Catégorie du partenaire
url:
type: string
nullable: true
format: uri
description: Site web du partenaire
logo:
type: string
nullable: true
format: uri
description: URL du logo
description:
type: string
nullable: true
description: Description du partenaire
widget:
type: boolean
description: Le partenaire dispose de droits widget
api:
type: boolean
description: Le partenaire dispose de droits API
campaign:
type: boolean
description: Le partenaire dispose de droits campagne
annonceur:
type: boolean
description: Le partenaire est annonceur (publie des missions)
# ── Partenaire avec exclusions ─────────────────────────────────────────────
PartnerWithExclusions:
allOf:
- $ref: "#/components/schemas/Partner"
- type: object
properties:
excludedOrganizations:
type: array
description: Organisations exclues de la diffusion vers ce partenaire
items:
type: object
properties:
publisherOrganizationId:
type: string
excludedForDiffuseurId:
type: string
# ── Partenaire avec statut d'exclusion ────────────────────────────────────
PartnerWithExclusionFlag:
allOf:
- $ref: "#/components/schemas/Partner"
- type: object
properties:
excluded:
type: boolean
description: Cette organisation est exclue de la diffusion vers ce partenaire
clicks:
type: integer
description: Nombre de clics vers les missions de cette organisation au cours des 30 derniers jours
# ── Règle de diffusion ────────────────────────────────────────────────────
DiffusionRule:
type: object
description: |
Règle de diffusion appliquée aux missions d'un annonceur pour un diffuseur donné.
Une mission n'est diffusée vers le diffuseur que si elle satisfait l'ensemble des règles configurées.
properties:
id:
type: string
description: Identifiant de la règle
example: "9b1c2d3e-4f56-7890-abcd-ef0123456789"
field:
type: string
description: |
Champ de la mission évalué par la règle. Valeurs possibles :
`type`, `publisherOrganizationId`, `publisherOrganization.clientId`,
`publisherOrganization.parentOrganizations`.
example: "type"
fieldType:
type: string
nullable: true
description: Type de la valeur évaluée (par défaut `string`)
example: "string"
operator:
type: string
description: |
Opérateur de comparaison. Valeurs possibles :
`is`, `is_not`, `contains`, `does_not_contain`, `starts_with`,
`is_greater_than`, `is_less_than`, `exists`, `does_not_exist`.
example: "is_not"
value:
type: string
description: Valeur comparée au champ de la mission
example: "benevolat"
# ── Diffuseur avec ses règles ──────────────────────────────────────────────
DiffuseurWithRules:
type: object
description: Partenaire diffuseur associé à l'annonceur, accompagné des règles de diffusion configurées
properties:
id:
type: string
description: Identifiant du diffuseur
example: "5f5931496c7ea514150a818f"
name:
type: string
description: Nom du diffuseur
example: "JeVeuxAider.gouv.fr"
logo:
type: string
nullable: true
format: uri
description: URL du logo du diffuseur
rules:
type: array
description: Règles de diffusion configurées pour ce diffuseur
items:
$ref: "#/components/schemas/DiffusionRule"
diffuse:
type: boolean
description: |
Présent uniquement lorsque les paramètres `field` et `value` sont fournis.
Indique si ce diffuseur diffuserait la valeur recherchée : `false` si une règle
d'exclusion (`does_not_contain`, `is_not`, `does_not_exist`) sur ce champ l'exclut, `true` sinon.
example: false
# ── Erreur ─────────────────────────────────────────────────────────────────
Error:
type: object
properties:
ok:
type: boolean
example: false
code:
type: string
example: "NOT_FOUND"
message:
description: Détail de l'erreur (peut être un objet Zod ou une chaîne)
# ── Réponses réutilisables ──────────────────────────────────────────────────
responses:
BadRequest:
description: Paramètres invalides
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
examples:
invalid_body:
value:
ok: false
code: "INVALID_BODY"
message: "clientId is required"
invalid_params:
value:
ok: false
code: "INVALID_PARAMS"
message: "Invalid path parameter"
Unauthorized:
description: Clé API manquante ou invalide
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
example:
ok: false
code: "UNAUTHORIZED"
message: "Unauthorized"
NotFound:
description: Ressource introuvable
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
example:
ok: false
code: "NOT_FOUND"
message: "Mission not found"
Forbidden:
description: Accès refusé
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
example:
ok: false
code: "FORBIDDEN"
message: "Mission not accessible"
Conflict:
description: Conflit — la ressource existe déjà
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
example:
ok: false
code: "RESSOURCE_ALREADY_EXIST"
message: "A mission with this clientId already exists for this publisher"
TooManyRequests:
description: Limite de débit atteinte
headers:
X-RateLimit-Limit:
schema:
type: integer
description: Nombre maximum de requêtes par fenêtre
X-RateLimit-Remaining:
schema:
type: integer
description: Nombre de requêtes restantes
Retry-After:
schema:
type: integer
description: Secondes à attendre avant de réessayer
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
example:
ok: false
code: "TOO_MANY_REQUESTS"
message: "Rate limit exceeded"
# ──────────────────────────────────────────────────────────────────────────────
# Paths
# ──────────────────────────────────────────────────────────────────────────────
paths:
# ────────────────────────────────────────────────────────────────────────────
# v2 — Missions
# ────────────────────────────────────────────────────────────────────────────
/v2/mission:
post:
summary: Créer une mission
description: |
Crée une nouvelle mission pour votre organisation.
La mission est immédiatement soumise aux règles de modération automatique :
si elle est incomplète (description trop courte, pas d'adresse, etc.), le champ
"statusCode" sera positionné à "REFUSED" avec un commentaire explicatif.
> **Rate limiting** : endpoint soumis à limitation de débit.
operationId: createMission
tags: [Missions]
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [clientId, title]
properties:
clientId:
type: string
description: Identifiant unique de la mission dans votre système d'information (immuable)
example: "mission-2024-001"
title:
type: string
description: Titre de la mission
example: "Animateur bénévole en maison de retraite"
description:
type: string
description: |
Description complète de la mission. Texte brut ou HTML acceptés.
La valeur fournie est conservée pour le rendu riche. Si du HTML est fourni, elle est aussi convertie en texte brut pour les usages internes, la recherche et la modération.
**Recommandations** :
- Utiliser le format HTML pour une meilleure lisibilité lors de la diffusion (sauts de ligne, gras, listes)
- Structurer en plusieurs sections pour agréger des informations provenant de champs différents dans votre système
- La description est limitée à 20 000 caractères
example: "EN QUELQUES MOTS
Favoriser la mixité au sein du club
VOTRE MISSION DE SERVICE CIVIQUE
Objectifs
- Développer la féminisation et favoriser l'accès à la pratique du football des jeunes filles
Actions
- Accompagner les éducateurs dans le projet éducatif féminin
- Mettre en place des actions en faveur de la mixité
- Sensibiliser les jeunes filles éloignées de la pratique sportive
"
applicationUrl:
type: string
format: uri
description: URL de la page où l'utilisateur sera redirigé pour candidater (URL de la page présentant la mission)
example: "https://www.example.org/missions/animateur-maison-retraite"
image:
type: string
format: uri
description: URL de l'image de la mission. Si absent, l'API Engagement utilise une image de sa bibliothèque selon le domaine.
metadata:
type: string
description: Métadonnées libres associées à la mission.
domain:
type: string
description: |
Domaine d'action de la mission. Valeurs possibles :
`animaux`, `autre`, `batiment-industrie-logistique`, `benevolat-competences`, `communication`, `culture-loisirs`, `education`, `emploi`, `environnement`, `gestion-finance-droit`, `humanitaire`, `memoire-et-citoyennete`, `numerique`, `prevention-protection`, `recherche`, `sante`, `service-public-defense-securite`, `sport`, `solidarite-insertion`, `vivre-ensemble`.
> Une demande d'ajout de valeur peut être faite auprès de l'équipe API Engagement.
example: "sante"
activities:
type: array
items:
type: string
description: |
Activité(s) principale(s) de la mission. Valeurs possibles :
`accueil-de-public`, `aide-psychologique`, `activites-manuelles`, `alphabetisation`, `animation`, `Animation, Valorisation`, `art`, `autre`, `bricolage`, `collecte`, `communication`, `comptabilite-finance`, `conseil`, `distribution`, `documentation-traduction`, `ecoute-permanence`, `encadrement-d-equipes`, `enseignement-formation`, `gestion-de-projets`, `gestion-recherche-des-partenariats`, `informatique`, `jardinage`, `juridique`, `logistique`, `lutte-contre-isolement`, `Médiation, Information`, `mentorat-parrainage`, `mission-internationale`, `Préservation, Patrimoine`, `Prévention, Sensibilisation`, `ramassage-dechets`, `recrutement`, `responsabilites-associatives`, `sante-soins`, `Secours, Aide`, `secourisme`, `sensibilisation`, `soins-animaux`, `Soutien, Accompagnement`, `soutien-scolaire`, `sport`, `taches-administratives`, `Transmission, Pédagogie`, `visites`, `operations-militaires`, `sciences-humaines-social`, `restauration-hotellerie`, `maintenance-technique`, `gestion-ressources-humaines`, `gestion-entretien-patrimoine`.
> Une demande d'ajout de valeur peut être faite auprès de l'équipe API Engagement.
example: ["animation", "lutte-contre-isolement"]
tags:
type: array
items:
type: string
description: Mots-clés personnalisés pour taguer la mission. Chaque élément du tableau est un tag distinct.
example: ["Ecologie", "Sport", "Solidarité"]
audience:
type: array
items:
type: string
description: |
Les bénéficiaires de la mission — à qui la mission s'adresse, le public auquel sera confronté la personne qui s'engage.
example: ["Tous publics"]
requirements:
type: array
items:
type: string
description: Pré-requis relatifs à la mission.
example: ["Niveau d'étude : BAC+2", "Connaissance de langue anglaise"]
softSkills:
type: array
items:
type: string
description: |
Les compétences générales requises pour la mission. Ce champ ne repose pas sur un référentiel de compétence structuré.
example: ["Écoute active", "Communication orale"]
romeSkills:
type: array
items:
type: string
description: |
Code OGR Macro du ROME 4.0. Ce champ repose sur le référentiel "Arborescence simplifiée des compétences" (section "Arborescence du ROME").
example: ["300412", "300361"]
remote:
type: string
enum: [no, possible, full, local]
description: "Politique de télétravail. Valeurs possibles : `no` (présentiel uniquement), `possible` (distanciel possible), `full` (100% distanciel), `local` (sur site, à proximité)"
example: "no"
schedule:
type: string
description: Rythme de la mission (texte libre)
example: "2 heures par semaine"
startAt:
type: string
format: date-time
description: "Date de début de la mission souhaitée. Format ISO 8601. Défaut : now()"
example: "2024-09-01T00:00:00.000Z"
endAt:
type: string
format: date-time
description: "Date de fin de la mission souhaitée. Format ISO 8601. Défaut : now()"
example: "2025-06-30T00:00:00.000Z"
postedAt:
type: string
format: date-time
description: "Date de première publication de la mission. Format ISO 8601."
example: "2024-06-15T09:00:00.000Z"
places:
type: integer
minimum: 1
default: 1
description: |
Nombre de places disponibles pour la mission. Ce nombre doit être mis à jour dès qu'il évolue dans votre système afin que l'API Engagement dispose toujours de la donnée la plus récente.
compensationAmount:
type: number
description: Montant minimum de l'indemnisation. Utilisé seul ou comme borne basse d'une fourchette avec `compensationAmountMax`.
example: 0
compensationAmountMax:
type: number
description: Montant maximum de l'indemnisation. Si renseigné, doit être supérieur ou égal à `compensationAmount` (ex. 0–13 €/h).
example: 13
compensationUnit:
type: string
enum: [hour, day, month, year]
description: "Période de l'indemnisation pour le montant fourni. Valeurs possibles : `year`, `month`, `day`, `hour`"
compensationType:
type: string
enum: [gross, net]
description: "Type d'indemnisation. Valeurs possibles : `gross` (brut), `net` (net)"
openToMinors:
type: boolean
description: Mission ouverte aux mineurs.
reducedMobilityAccessible:
type: boolean
description: Mission accessible aux personnes à mobilité réduite.
closeToTransport:
type: boolean
description: Mission proche des transports en commun.
addresses:
type: array
items:
$ref: "#/components/schemas/Address"
description: |
Ensemble des localisations où se déroule la mission. Si la mission se tient dans plusieurs lieux, renseignez autant d'objets que de localisations. Pour une mission en lieu unique, le tableau ne contient qu'un seul objet.
example:
- street: "12 rue de la Paix"
postalCode: "75001"
city: "Paris"
departmentCode: "75"
departmentName: "Paris"
region: "Île-de-France"
country: "France"
type:
type: string
enum: [benevolat, volontariat_service_civique, volontariat_sapeurs_pompiers, volontariat_reserve_operationnelle]
description: Type de mission d'engagement
organizationClientId:
type: string
description: Identifiant de l'organisation dans votre système. L'organisation désigne l'entité qui accueille le bénévole ou le volontaire.
organizationName:
type: string
description: "Nom de l'organisation. Requis si un autre champ `organization*` est renseigné."
organizationDescription:
type: string
description: Description de l'organisation.
organizationUrl:
type: string
format: uri
description: Lien de l'organisation (ex. page de présentation sur votre site).
organizationType:
type: string
description: Type de l'organisation.
example: "Association déclarée"
organizationLogo:
type: string
format: uri
description: URL de l'image de l'organisation.
organizationRNA:
type: string
description: Numéro RNA de l'organisation. Uniquement valable pour les organisations de type association.
example: "W353002476"
organizationSiren:
type: string
description: SIREN de l'organisation.
example: "339863417"
organizationSiret:
type: string
description: SIRET de l'organisation.
example: "33986341700418"
organizationFullAddress:
type: string
description: Adresse de l'organisation. Pas de format strict attendu (contrairement à l'adresse de la mission).
organizationPostCode:
type: string
description: Code postal de l'organisation.
example: "94170"
organizationCity:
type: string
description: Ville de l'organisation.
example: "Le Perreux-sur-Marne"
organizationDepartmentCode:
type: string
description: Code du département de l'organisation.
example: "94"
organizationDepartmentName:
type: string
description: Nom du département de l'organisation.
example: "Val de Marne"
organizationStatusJuridique:
type: string
description: Statut juridique de l'organisation.
organizationBeneficiaries:
type: array
items:
type: string
description: Bénéficiaires de l'organisation.
organizationActions:
type: array
items:
type: string
description: Principales actions menées par l'organisation.
example: ["Animation", "Valorisation", "Préservation"]
organizationReseaux:
type: array
items:
type: string
description: Réseau de l'organisation. Ce champ sert à renseigner les organisations ayant des antennes locales et dépendant d'un réseau national.
responses:
"201":
description: Mission créée
content:
application/json:
schema:
type: object
properties:
ok:
type: boolean
example: true
data:
$ref: "#/components/schemas/MissionV2"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"409":
$ref: "#/components/responses/Conflict"
"429":
$ref: "#/components/responses/TooManyRequests"
/v2/mission/{clientId}:
put:
summary: Modifier une mission
description: |
Mise à jour partielle d'une mission (sémantique PATCH).
Seuls les champs fournis dans le corps sont modifiés.
Les règles de modération automatique sont réévaluées sur l'état complet résultant.
> **Rate limiting** : endpoint soumis à limitation de débit.
operationId: updateMission
tags: [Missions]
parameters:
- name: clientId
in: path
required: true
description: Identifiant de la mission dans votre système
schema:
type: string
example: "mission-2024-001"
requestBody:
required: true
content:
application/json:
schema:
type: object
description: Tous les champs sont optionnels — seuls les champs fournis sont mis à jour
properties:
title:
type: string
description: Titre de la mission
example: "Animateur bénévole en maison de retraite"
description:
type: string
description: |
Description complète de la mission. Texte brut ou HTML acceptés.
La valeur fournie est conservée pour le rendu riche. Si du HTML est fourni, elle est aussi convertie en texte brut pour les usages internes, la recherche et la modération.
**Recommandations** :
- Utiliser le format HTML pour une meilleure lisibilité lors de la diffusion (sauts de ligne, gras, listes)
- Structurer en plusieurs sections pour agréger des informations provenant de champs différents dans votre système
- La description est limitée à 20 000 caractères
example: "EN QUELQUES MOTS
Favoriser la mixité au sein du club
VOTRE MISSION DE SERVICE CIVIQUE
Objectifs
- Développer la féminisation et favoriser l'accès à la pratique du football des jeunes filles
Actions
- Accompagner les éducateurs dans le projet éducatif féminin
- Mettre en place des actions en faveur de la mixité
- Sensibiliser les jeunes filles éloignées de la pratique sportive
"
applicationUrl:
type: string
format: uri
description: URL de la page où l'utilisateur sera redirigé pour candidater (URL de la page présentant la mission)
example: "https://www.example.org/missions/animateur-maison-retraite"
image:
type: string
format: uri
description: URL de l'image de la mission. Si absent, l'API Engagement utilise une image de sa bibliothèque selon le domaine.
metadata:
type: string
description: Métadonnées libres associées à la mission.
domain:
type: string
description: |
Domaine d'action de la mission. Valeurs possibles :
`animaux`, `autre`, `batiment-industrie-logistique`, `benevolat-competences`, `communication`, `culture-loisirs`, `education`, `emploi`, `environnement`, `gestion-finance-droit`, `humanitaire`, `memoire-et-citoyennete`, `numerique`, `prevention-protection`, `recherche`, `sante`, `service-public-defense-securite`, `sport`, `solidarite-insertion`, `vivre-ensemble`.
> Une demande d'ajout de valeur peut être faite auprès de l'équipe API Engagement.
example: "sante"
activities:
type: array
items:
type: string
description: |
Activité(s) principale(s) de la mission. Valeurs possibles :
`accueil-de-public`, `aide-psychologique`, `activites-manuelles`, `alphabetisation`, `animation`, `Animation, Valorisation`, `art`, `autre`, `bricolage`, `collecte`, `communication`, `comptabilite-finance`, `conseil`, `distribution`, `documentation-traduction`, `ecoute-permanence`, `encadrement-d-equipes`, `enseignement-formation`, `gestion-de-projets`, `gestion-recherche-des-partenariats`, `informatique`, `jardinage`, `juridique`, `logistique`, `lutte-contre-isolement`, `Médiation, Information`, `mentorat-parrainage`, `mission-internationale`, `Préservation, Patrimoine`, `Prévention, Sensibilisation`, `ramassage-dechets`, `recrutement`, `responsabilites-associatives`, `sante-soins`, `Secours, Aide`, `secourisme`, `sensibilisation`, `soins-animaux`, `Soutien, Accompagnement`, `soutien-scolaire`, `sport`, `taches-administratives`, `Transmission, Pédagogie`, `visites`, `operations-militaires`, `sciences-humaines-social`, `restauration-hotellerie`, `maintenance-technique`, `gestion-ressources-humaines`, `gestion-entretien-patrimoine`.
> Une demande d'ajout de valeur peut être faite auprès de l'équipe API Engagement.
example: ["animation", "lutte-contre-isolement"]
tags:
type: array
items:
type: string
description: Mots-clés personnalisés pour taguer la mission. Chaque élément du tableau est un tag distinct.
example: ["Ecologie", "Sport", "Solidarité"]
audience:
type: array
items:
type: string
description: |
Les bénéficiaires de la mission — à qui la mission s'adresse, le public auquel sera confronté la personne qui s'engage.
example: ["Tous publics"]
requirements:
type: array
items:
type: string
description: Pré-requis relatifs à la mission.
example: ["Niveau d'étude : BAC+2", "Connaissance de langue anglaise"]
softSkills:
type: array
items:
type: string
description: |
Les compétences générales requises pour la mission. Ce champ ne repose pas sur un référentiel de compétence structuré.
example: ["Écoute active", "Communication orale"]
romeSkills:
type: array
items:
type: string
description: |
Code OGR Macro du ROME 4.0. Ce champ repose sur le référentiel "Arborescence simplifiée des compétences" (section "Arborescence du ROME").
example: ["300412", "300361"]
remote:
type: string
enum: [no, possible, full, local]
description: "Politique de télétravail. Valeurs possibles : `no` (présentiel uniquement), `possible` (distanciel possible), `full` (100% distanciel), `local` (sur site, à proximité)"
example: "no"
schedule:
type: string
description: Rythme de la mission (texte libre)
example: "2 heures par semaine"
startAt:
type: string
format: date-time
description: "Date de début de la mission souhaitée. Format ISO 8601. Défaut : now()"
example: "2024-09-01T00:00:00.000Z"
endAt:
type: string
format: date-time
description: "Date de fin de la mission souhaitée. Format ISO 8601. Défaut : now()"
example: "2025-06-30T00:00:00.000Z"
postedAt:
type: string
format: date-time
description: "Date de première publication de la mission. Format ISO 8601."
example: "2024-06-15T09:00:00.000Z"
places:
type: integer
minimum: 1
compensationAmount:
type: number
description: Montant minimum de l'indemnisation. Utilisé seul ou comme borne basse d'une fourchette avec `compensationAmountMax`.
example: 0
compensationAmountMax:
type: number
description: Montant maximum de l'indemnisation. Si renseigné, doit être supérieur ou égal à `compensationAmount` (ex. 0–13 €/h).
example: 13
compensationUnit:
type: string
enum: [hour, day, month, year]
description: "Période de l'indemnisation pour le montant fourni. Valeurs possibles : `year`, `month`, `day`, `hour`"
compensationType:
type: string
enum: [gross, net]
description: "Type d'indemnisation. Valeurs possibles : `gross` (brut), `net` (net)"
openToMinors:
type: boolean
description: Mission ouverte aux mineurs.
reducedMobilityAccessible:
type: boolean
description: Mission accessible aux personnes à mobilité réduite.
closeToTransport:
type: boolean
description: Mission proche des transports en commun.
addresses:
type: array
items:
$ref: "#/components/schemas/Address"
description: |
Ensemble des localisations où se déroule la mission. Si la mission se tient dans plusieurs lieux, renseignez autant d'objets que de localisations. Pour une mission en lieu unique, le tableau ne contient qu'un seul objet.
example:
- street: "12 rue de la Paix"
postalCode: "75001"
city: "Paris"
departmentCode: "75"
departmentName: "Paris"
region: "Île-de-France"
country: "France"
type:
type: string
enum: [benevolat, volontariat_service_civique, volontariat_sapeurs_pompiers, volontariat_reserve_operationnelle]
description: Type de mission d'engagement
organizationClientId:
type: string
description: Identifiant de l'organisation dans votre système. L'organisation désigne l'entité qui accueille le bénévole ou le volontaire.
organizationName:
type: string
description: "Nom de l'organisation. Requis si un autre champ `organization*` est renseigné."
organizationDescription:
type: string
description: Description de l'organisation.
organizationUrl:
type: string
format: uri
description: Lien de l'organisation (ex. page de présentation sur votre site).
organizationType:
type: string
description: Type de l'organisation.
example: "Association déclarée"
organizationLogo:
type: string
format: uri
description: URL de l'image de l'organisation.
organizationRNA:
type: string
description: Numéro RNA de l'organisation. Uniquement valable pour les organisations de type association.
example: "W353002476"
organizationSiren:
type: string
description: SIREN de l'organisation.
example: "339863417"
organizationSiret:
type: string
description: SIRET de l'organisation.
example: "33986341700418"
organizationFullAddress:
type: string
description: Adresse de l'organisation. Pas de format strict attendu (contrairement à l'adresse de la mission).
organizationPostCode:
type: string
description: Code postal de l'organisation.
example: "94170"
organizationCity:
type: string
description: Ville de l'organisation.
example: "Le Perreux-sur-Marne"
organizationStatusJuridique:
type: string
description: Statut juridique de l'organisation.
organizationBeneficiaries:
type: array
items:
type: string
description: Bénéficiaires de l'organisation.
organizationActions:
type: array
items:
type: string
description: Principales actions menées par l'organisation.
example: ["Animation", "Valorisation", "Préservation"]
organizationReseaux:
type: array
items:
type: string
description: Réseau de l'organisation. Ce champ sert à renseigner les organisations ayant des antennes locales et dépendant d'un réseau national.
responses:
"200":
description: Mission mise à jour
content:
application/json:
schema:
type: object
properties:
ok:
type: boolean
example: true
data:
$ref: "#/components/schemas/MissionV2"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"404":
$ref: "#/components/responses/NotFound"
"429":
$ref: "#/components/responses/TooManyRequests"
delete:
summary: Supprimer une mission
description: |
Suppression douce (soft delete) d'une mission. L'opération est idempotente :
si la mission est déjà supprimée, la réponse est identique à une suppression réussie.
> **Rate limiting** : endpoint soumis à limitation de débit.
operationId: deleteMission
tags: [Missions]
parameters:
- name: clientId
in: path
required: true
description: Identifiant de la mission dans votre système
schema:
type: string
example: "mission-2024-001"
responses:
"200":
description: Mission supprimée
content:
application/json:
schema:
type: object
properties:
ok:
type: boolean
example: true
data:
type: object
properties:
clientId:
type: string
example: "mission-2024-001"
deletedAt:
type: string
format: date-time
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"404":
$ref: "#/components/responses/NotFound"
"429":
$ref: "#/components/responses/TooManyRequests"
# ────────────────────────────────────────────────────────────────────────────
# v2 — Activités
# ────────────────────────────────────────────────────────────────────────────
/v2/activity/{id}:
get:
summary: Récupérer une activité
description: |
Récupère une activité (candidature ou création de compte) par son identifiant
ou par son "clientEventId". En cas d'ambiguïté (même "clientEventId" pour un
"apply" et un "account"), précisez le paramètre "type".
operationId: getActivity
tags: [Activités]
parameters:
- name: id
in: path
required: true
description: Identifiant interne ou "clientEventId" de l'activité
schema:
type: string
example: "64a1b2c3d4e5f6789abc0099"
- name: type
in: query
required: false
description: Type de l'activité (requis en cas d'ambiguïté sur le "clientEventId")
schema:
type: string
enum: [apply, account]
responses:
"200":
description: Activité trouvée
content:
application/json:
schema:
type: object
properties:
ok:
type: boolean
example: true
data:
$ref: "#/components/schemas/Activity"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"404":
$ref: "#/components/responses/NotFound"
"409":
description: Ambiguïté sur le clientEventId — précisez le paramètre "type"
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
put:
summary: Mettre à jour le statut d'une activité
description: |
Met à jour le statut d'une candidature ou d'une création de compte.
Utilisez ce endpoint pour notifier l'API des décisions prises sur les candidatures
(validation, refus, annulation, etc.).
operationId: updateActivity
tags: [Activités]
parameters:
- name: id
in: path
required: true
description: Identifiant interne ou "clientEventId" de l'activité
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [status]
properties:
status:
type: string
enum: [PENDING, VALIDATED, CANCELED, REFUSED, CARRIED_OUT]
description: Nouveau statut de l'activité
example: "VALIDATED"
type:
type: string
enum: [apply, account]
description: Type de l'activité (requis en cas d'ambiguïté)
responses:
"200":
description: Activité mise à jour
content:
application/json:
schema:
type: object
properties:
ok:
type: boolean
example: true
data:
$ref: "#/components/schemas/Activity"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"404":
$ref: "#/components/responses/NotFound"
"409":
description: Ambiguïté sur le clientEventId — précisez le paramètre "type"
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
/v2/activity:
post:
summary: Créer une activité
description: |
Enregistre un événement d'engagement (candidature ou création de compte)
lié à un clic tracé par l'API ou directement à une mission.
Le "clickId" doit correspondre à un clic enregistré par l'API Engagement.
Le "missionId" permet à un diffuseur autorisé de déclarer une activité sans clic.
Le "missionClientId" correspond à l'identifiant métier d'une mission du publisher authentifié.
Au moins un champ parmi "clickId", "missionId" et "missionClientId" doit être fourni.
Le champ "missionId" ne doit pas être combiné avec "clickId" ou "missionClientId".
operationId: createActivity
tags: [Activités]
requestBody:
required: true
content:
application/json:
schema:
type: object
anyOf:
- required: [clickId]
- required: [missionId]
- required: [missionClientId]
not:
anyOf:
- required: [clickId, missionId]
- required: [missionId, missionClientId]
properties:
type:
type: string
enum: [apply, account]
default: apply
description: Type d'événement (défaut "apply")
clickId:
type: string
description: Identifiant du clic d'origine
example: "64a1b2c3d4e5f6789abc0088"
missionId:
type: string
description: Identifiant interne API Engagement de la mission, utilisable par un diffuseur autorisé sans clickId
example: "64a1b2c3d4e5f6789abc0001"
missionClientId:
type: string
description: Identifiant métier de la mission côté publisher authentifié
tag:
type: string
description: Tag libre (optionnel)
responses:
"200":
description: Activité créée
content:
application/json:
schema:
type: object
properties:
ok:
type: boolean
example: true
data:
$ref: "#/components/schemas/Activity"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
description: Clic ou mission introuvable
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
# ────────────────────────────────────────────────────────────────────────────
# v0 — Recherche de missions
# ────────────────────────────────────────────────────────────────────────────
/v0/mission:
get:
summary: Rechercher des missions
description: |
Retourne les missions diffusées par vos partenaires, filtrées selon vos critères.
Les résultats sont limités aux partenaires autorisés pour votre clé API.
Les paramètres "activity", "city", "clientId", "country", "departmentName",
"domain", "organizationRNA", "organizationStatusJuridique", "publisher",
"remote" et "type" acceptent une valeur unique ou un tableau de valeurs
(ex. "?domain=sante&domain=education").
operationId: searchMissions
tags: [Missions]
parameters:
- name: limit
in: query
schema:
type: integer
minimum: 0
maximum: 10000
default: 25
description: Nombre de résultats (défaut 25, max 10 000)
- name: skip
in: query
schema:
type: integer
minimum: 0
default: 0
description: Décalage pour la pagination
- name: keywords
in: query
schema:
type: string
description: Recherche textuelle (titre, description, organisation)
example: "cuisine solidaire"
- name: domain
in: query
schema:
oneOf:
- type: string
- type: array
items:
type: string
description: Domaine d'action
example: "sante"
- name: activity
in: query
schema:
oneOf:
- type: string
- type: array
items:
type: string
description: Activité proposée
- name: type
in: query
schema:
oneOf:
- type: string
enum: [benevolat, volontariat_service_civique, volontariat_sapeurs_pompiers, volontariat_reserve_operationnelle]
- type: array
items:
type: string
enum: [benevolat, volontariat_service_civique, volontariat_sapeurs_pompiers, volontariat_reserve_operationnelle]
description: "Type d'engagement"
- name: remote
in: query
schema:
oneOf:
- type: string
- type: array
items:
type: string
description: "Politique de télétravail : no, possible, full, local"
- name: lat
in: query
schema:
type: number
format: double
description: Latitude (requis avec "lon" pour la recherche géographique)
example: 48.8566
- name: lon
in: query
schema:
type: number
format: double
description: Longitude (requis avec "lat" pour la recherche géographique)
example: 2.3522
- name: distance
in: query
schema:
type: string
description: "Rayon de recherche géographique (ex. 25km, 50km). Défaut : 50km"
example: "25km"
- name: city
in: query
schema:
oneOf:
- type: string
- type: array
items:
type: string
description: Filtre par ville
- name: departmentName
in: query
schema:
oneOf:
- type: string
- type: array
items:
type: string
description: Filtre par département
example: "Rhône"
- name: country
in: query
schema:
oneOf:
- type: string
- type: array
items:
type: string
description: Filtre par pays
- name: clientId
in: query
schema:
oneOf:
- type: string
- type: array
items:
type: string
description: Filtre par identifiant client
- name: publisher
in: query
schema:
oneOf:
- type: string
- type: array
items:
type: string
description: Filtre sur les identifiants de partenaires diffuseurs
- name: organizationRNA
in: query
schema:
oneOf:
- type: string
- type: array
items:
type: string
description: Filtre par numéro RNA de l'organisation
- name: organizationStatusJuridique
in: query
schema:
oneOf:
- type: string
- type: array
items:
type: string
description: Filtre par forme juridique de l'organisation
- name: openToMinors
in: query
schema:
type: string
enum: ["true", "false", "yes", "no", "1", "0"]
description: Missions ouvertes aux mineurs uniquement
- name: reducedMobilityAccessible
in: query
schema:
type: string
enum: ["true", "false", "yes", "no", "1", "0"]
description: Missions accessibles PMR uniquement
- name: startAt
in: query
schema:
type: string
description: "Filtre sur la date de début (ex. >2024-01-01, <2024-12-31)"
- name: createdAt
in: query
schema:
type: string
description: "Filtre sur la date de création (ex. >2024-01-01)"
responses:
"200":
description: Liste de missions
content:
application/json:
schema:
type: object
properties:
ok:
type: boolean
example: true
total:
type: integer
description: Nombre total de résultats correspondants
example: 1234
limit:
type: integer
example: 25
skip:
type: integer
example: 0
data:
type: array
items:
$ref: "#/components/schemas/MissionLegacy"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
/v0/mission/search:
get:
summary: Rechercher des missions avec facettes
description: |
Identique à "GET /v0/mission" mais retourne également des facettes
(agrégations) sur les domaines, activités et départements pour faciliter
la construction de filtres dynamiques.
operationId: searchMissionsWithFacets
tags: [Missions]
parameters:
- name: limit
in: query
schema:
type: integer
minimum: 0
maximum: 10000
default: 25
- name: skip
in: query
schema:
type: integer
minimum: 0
default: 0
- name: keywords
in: query
schema:
type: string
- name: domain
in: query
schema:
oneOf:
- type: string
- type: array
items:
type: string
- name: activity
in: query
schema:
oneOf:
- type: string
- type: array
items:
type: string
- name: type
in: query
schema:
oneOf:
- type: string
- type: array
items:
type: string
- name: remote
in: query
schema:
oneOf:
- type: string
- type: array
items:
type: string
- name: lat
in: query
schema:
type: number
format: double
- name: lon
in: query
schema:
type: number
format: double
- name: distance
in: query
schema:
type: string
- name: departmentName
in: query
schema:
oneOf:
- type: string
- type: array
items:
type: string
- name: openToMinors
in: query
schema:
type: string
enum: ["true", "false", "yes", "no", "1", "0"]
- name: reducedMobilityAccessible
in: query
schema:
type: string
enum: ["true", "false", "yes", "no", "1", "0"]
responses:
"200":
description: Liste de missions avec facettes
content:
application/json:
schema:
type: object
properties:
ok:
type: boolean
example: true
total:
type: integer
example: 1234
hits:
type: array
items:
$ref: "#/components/schemas/MissionLegacy"
facets:
type: object
description: Agrégations pour les filtres dynamiques
properties:
domains:
type: array
items:
type: object
properties:
key:
type: string
doc_count:
type: integer
activities:
type: array
items:
type: object
properties:
key:
type: string
doc_count:
type: integer
departmentName:
type: array
items:
type: object
properties:
key:
type: string
doc_count:
type: integer
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
/v0/mission/{id}:
get:
summary: Récupérer une mission par ID
operationId: getMission
tags: [Missions]
parameters:
- name: id
in: path
required: true
description: Identifiant interne de la mission
schema:
type: string
example: "64a1b2c3d4e5f6789abc0001"
responses:
"200":
description: Mission trouvée
content:
application/json:
schema:
type: object
properties:
ok:
type: boolean
example: true
data:
$ref: "#/components/schemas/MissionLegacy"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"404":
$ref: "#/components/responses/NotFound"
# ────────────────────────────────────────────────────────────────────────────
# v0 — Mes missions
# ────────────────────────────────────────────────────────────────────────────
/v0/mymission:
get:
summary: Lister mes missions
description: Retourne toutes les missions publiées par votre organisation.
operationId: listMyMissions
tags: [Mes missions]
parameters:
- name: limit
in: query
schema:
type: integer
minimum: 0
maximum: 10000
default: 50
description: Nombre de résultats (défaut 50, max 10 000)
- name: skip
in: query
schema:
type: integer
minimum: 0
default: 0
description: Décalage pour la pagination
responses:
"200":
description: Liste de missions
content:
application/json:
schema:
type: object
properties:
ok:
type: boolean
example: true
total:
type: integer
example: 42
limit:
type: integer
example: 50
skip:
type: integer
example: 0
data:
type: array
items:
$ref: "#/components/schemas/MissionLegacy"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
/v0/mymission/{clientId}:
get:
summary: Récupérer une mission avec ses statistiques
description: Retourne une mission identifiée par son "clientId" ainsi que ses statistiques d'engagement (clics, candidatures, créations de compte).
operationId: getMyMission
tags: [Mes missions]
parameters:
- name: clientId
in: path
required: true
description: Identifiant de la mission dans votre système
schema:
type: string
example: "mission-2024-001"
responses:
"200":
description: Mission avec statistiques
content:
application/json:
schema:
type: object
properties:
ok:
type: boolean
example: true
data:
allOf:
- $ref: "#/components/schemas/MissionLegacy"
- type: object
properties:
stats:
$ref: "#/components/schemas/MissionStats"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"404":
$ref: "#/components/responses/NotFound"
/v0/mymission/{clientId}/stats:
get:
summary: Récupérer les statistiques d'une mission
description: Retourne uniquement les statistiques d'engagement d'une mission (clics, candidatures, créations de compte).
operationId: getMyMissionStats
tags: [Mes missions]
parameters:
- name: clientId
in: path
required: true
description: Identifiant de la mission dans votre système
schema:
type: string
example: "mission-2024-001"
responses:
"200":
description: Statistiques de la mission
content:
application/json:
schema:
type: object
properties:
ok:
type: boolean
example: true
data:
$ref: "#/components/schemas/MissionStats"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"404":
$ref: "#/components/responses/NotFound"
# ────────────────────────────────────────────────────────────────────────────
# v0 — Organisations
# ────────────────────────────────────────────────────────────────────────────
/v0/organization:
get:
summary: Rechercher des organisations
description: |
Recherche des organisations par nom, numéro RNA ou SIRET.
Au moins un critère de recherche est recommandé.
operationId: searchOrganizations
tags: [Organisations]
parameters:
- name: q
in: query
schema:
type: string
description: Recherche textuelle sur le nom
example: "Croix-Rouge"
- name: rna
in: query
schema:
type: string
description: Numéro RNA exact
example: "W751206979"
- name: siret
in: query
schema:
type: string
description: Numéro SIRET exact
example: "77567227221138"
- name: limit
in: query
schema:
type: integer
minimum: 0
maximum: 100
default: 25
description: Nombre de résultats (défaut 25, max 100)
- name: skip
in: query
schema:
type: integer
minimum: 0
default: 0
description: Décalage pour la pagination
responses:
"200":
description: Liste d'organisations
content:
application/json:
schema:
type: object
properties:
ok:
type: boolean
example: true
data:
type: array
items:
$ref: "#/components/schemas/Organization"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
/v0/myorganization/{organizationClientId}:
get:
summary: Consulter la diffusion d'une organisation
description: |
Retourne la liste des partenaires diffuseurs éligibles, avec pour chacun :
- le nombre de clics vers les missions de cette organisation sur les 30 derniers jours
- l'indicateur d'exclusion éventuelle
Utile pour piloter la stratégie de diffusion d'une organisation.
operationId: getOrganizationDiffusion
tags: [Organisations]
parameters:
- name: organizationClientId
in: path
required: true
description: Identifiant de l'organisation dans votre système
schema:
type: string
example: "org-croix-rouge-001"
responses:
"200":
description: Liste des partenaires diffuseurs avec statut d'exclusion
content:
application/json:
schema:
type: object
properties:
ok:
type: boolean
example: true
total:
type: integer
example: 8
data:
type: array
items:
$ref: "#/components/schemas/PartnerWithExclusionFlag"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"404":
$ref: "#/components/responses/NotFound"
put:
summary: Gérer les exclusions de diffusion d'une organisation
description: |
Définit la liste des partenaires diffuseurs **autorisés** pour une organisation.
Les partenaires non inclus dans "publisherIds" seront exclus de la diffusion.
> **Attention** : cette opération remplace intégralement les exclusions existantes.
operationId: updateOrganizationDiffusion
tags: [Organisations]
parameters:
- name: organizationClientId
in: path
required: true
description: Identifiant de l'organisation dans votre système
schema:
type: string
example: "org-croix-rouge-001"
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [publisherIds]
properties:
organizationName:
type: string
nullable: true
description: Nom de l'organisation (optionnel, mis à jour si fourni)
example: "Croix-Rouge française"
publisherIds:
type: array
items:
type: string
description: Liste des identifiants des partenaires **autorisés** à diffuser les missions de cette organisation
example: ["5f5931496c7ea514150a818f", "60a1b2c3d4e5f6789abc0001"]
responses:
"200":
description: Exclusions mises à jour
content:
application/json:
schema:
type: object
properties:
ok:
type: boolean
example: true
total:
type: integer
example: 8
data:
type: array
description: Liste complète des partenaires avec leur statut d'exclusion mis à jour
items:
$ref: "#/components/schemas/PartnerWithExclusionFlag"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
# ────────────────────────────────────────────────────────────────────────────
# v0 — Partenaires diffuseurs
# ────────────────────────────────────────────────────────────────────────────
/v0/publisher:
get:
summary: Lister les partenaires diffuseurs
description: |
Retourne la liste des partenaires diffuseurs qui diffusent vos missions,
avec les exclusions d'organisations éventuellement configurées.
operationId: listPartners
tags: [Partenaires]
responses:
"200":
description: Liste des partenaires diffuseurs
content:
application/json:
schema:
type: object
properties:
ok:
type: boolean
example: true
total:
type: integer
example: 12
data:
type: array
items:
$ref: "#/components/schemas/PartnerWithExclusions"
"401":
$ref: "#/components/responses/Unauthorized"
/v0/publisher/{id}:
get:
summary: Récupérer un partenaire diffuseur
description: Retourne le détail d'un partenaire diffuseur, incluant les organisations exclues.
operationId: getPartner
tags: [Partenaires]
parameters:
- name: id
in: path
required: true
description: Identifiant du partenaire diffuseur
schema:
type: string
example: "5f5931496c7ea514150a818f"
responses:
"200":
description: Partenaire trouvé
content:
application/json:
schema:
type: object
properties:
ok:
type: boolean
example: true
data:
$ref: "#/components/schemas/PartnerWithExclusions"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"404":
$ref: "#/components/responses/NotFound"
# ────────────────────────────────────────────────────────────────────────────
# v0 — Règles de diffusion
# ────────────────────────────────────────────────────────────────────────────
/v0/diffusion-rule:
get:
summary: Lister les règles de diffusion
description: |
Retourne, pour chacun de vos partenaires diffuseurs, les règles de diffusion
que vous avez configurées en tant qu'annonceur. Ces règles déterminent quelles
missions sont diffusées vers chaque diffuseur.
Les paramètres `field` et `value` doivent être fournis ensemble (les deux ou aucun) :
lorsqu'ils sont présents, chaque diffuseur est en plus annoté d'un booléen `diffuse`
indiquant s'il diffuserait la valeur recherchée pour ce champ. Fournir un seul des
deux renvoie une erreur `400`.
operationId: listDiffusionRules
tags: [Règles de diffusion]
parameters:
- name: field
in: query
required: false
description: |
Champ sur lequel évaluer la diffusion. À fournir conjointement avec `value`.
Valeurs possibles : `type`, `publisherOrganizationId`,
`publisherOrganization.clientId`, `publisherOrganization.parentOrganizations`.
schema:
type: string
example: "publisherOrganization.parentOrganizations"
- name: value
in: query
required: false
description: Valeur recherchée sur le champ `field`. À fournir conjointement avec `field`.
schema:
type: string
example: "Marine nationale"
responses:
"200":
description: Liste des diffuseurs avec leurs règles de diffusion
content:
application/json:
schema:
type: object
properties:
ok:
type: boolean
example: true
total:
type: integer
description: Nombre de diffuseurs retournés
example: 3
data:
type: array
items:
$ref: "#/components/schemas/DiffuseurWithRules"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
post:
summary: Créer une règle de diffusion
description: |
Crée une règle de diffusion appliquée à un ou plusieurs de vos partenaires diffuseurs.
Seuls les diffuseurs effectivement associés à votre compte sont pris en compte ;
les autres identifiants fournis sont ignorés.
Une mission n'est diffusée vers un diffuseur que si elle satisfait l'ensemble
des règles configurées pour ce diffuseur.
L'opération est idempotente : si une règle identique (même `field`, `value`, `operator`
et `fieldType`) existe déjà pour un diffuseur, la règle existante est retournée plutôt
que dupliquée. Si une règle existe pour le même `field` et `value` mais avec un opérateur
différent, l'API renvoie une erreur `409` plutôt que de masquer silencieusement la demande.
operationId: createDiffusionRule
tags: [Règles de diffusion]
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [publisherIds, field, operator, value]
properties:
publisherIds:
type: array
minItems: 1
description: Identifiants des partenaires diffuseurs auxquels appliquer la règle
items:
type: string
example: ["5f5931496c7ea514150a818f", "60a1b2c3d4e5f6789abc0001"]
field:
type: string
description: |
Champ de la mission évalué par la règle. Valeurs possibles :
`type`, `publisherOrganizationId`, `publisherOrganization.clientId`,
`publisherOrganization.parentOrganizations`.
example: "type"
fieldType:
type: string
nullable: true
description: Type de la valeur évaluée (par défaut `string`)
example: "string"
operator:
type: string
description: |
Opérateur de comparaison. Valeurs possibles :
`is`, `is_not`, `contains`, `does_not_contain`, `starts_with`,
`is_greater_than`, `is_less_than`, `exists`, `does_not_exist`.
example: "is_not"
value:
type: string
description: Valeur comparée au champ de la mission
example: "benevolat"
responses:
"201":
description: Règle(s) créée(s)
content:
application/json:
schema:
type: object
properties:
ok:
type: boolean
example: true
total:
type: integer
description: Nombre de règles créées (une par diffuseur)
example: 2
data:
type: array
items:
allOf:
- type: object
properties:
publisherId:
type: string
description: Identifiant du diffuseur auquel s'applique la règle
example: "5f5931496c7ea514150a818f"
- $ref: "#/components/schemas/DiffusionRule"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"409":
$ref: "#/components/responses/Conflict"
/v0/diffusion-rule/{id}:
delete:
summary: Supprimer une règle de diffusion
description: |
Supprime une règle de diffusion que vous avez configurée. Seules les règles
rattachées à votre compte annonceur peuvent être supprimées.
operationId: deleteDiffusionRule
tags: [Règles de diffusion]
parameters:
- name: id
in: path
required: true
description: Identifiant de la règle de diffusion (règle enfant rattachée à votre scope d'annonceur)
schema:
type: string
example: "9b1c2d3e-4f56-7890-abcd-ef0123456789"
responses:
"200":
description: Règle supprimée
content:
application/json:
schema:
type: object
properties:
ok:
type: boolean
example: true
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
$ref: "#/components/responses/NotFound"