Ressources

Documents

Chaque point de terminaison Documents, avec la portée qu'il impose, le corps qu'il accepte, une réponse lisible et les refus qu'il peut renvoyer.

Lister les documents liés à un passeport.

get/organizations/{organization}/passports/{id}/documents

Portée: documents:read
Idempotency-Key: Non accepté
Renvoie: 200

Paramètres de chemin

organizationstringObligatoire

L'organisation pour laquelle cette requête agit. La clé doit disposer d'une autorisation sur celle-ci.

idstringObligatoire

L'identifiant de la ressource. Traitez-le comme une chaîne opaque.

Paramètres de requête

limitstringFacultatif

Le nombre d'enregistrements à renvoyer. Le serveur peut en renvoyer moins.

cursorstringFacultatif

Le next_cursor de la page précédente. Un curseur encode les filtres sous lesquels il a été émis ; l'envoyer avec d'autres filtres est refusé par cursor_invalid.

typestringFacultatif

Ne renvoyer que les documents de ce type.

access_tierstringFacultatif

Ne renvoyer que les documents publiés pour ce niveau d'audience.

Erreurs

Tous les refus que ce point de terminaison peut renvoyer, avec le statut qui les accompagne.

Requête

curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/documents?access_tier=public" \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY"

Réponse · 200

{
  "object": "list",
  "data": [
    {
      "object": "document",
      "id": "a3b8c2d1-5e64-4f79-8a0b-1c2d3e4f5a6b",
      "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/documents/a3b8c2d1-5e64-4f79-8a0b-1c2d3e4f5a6b",
      "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
      "passport_id": "2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
      "passport": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
      "type": "conformity_declaration",
      "access_tier": "public",
      "file_name": "doc-2026-kestrel.pdf",
      "display_name": "EU Declaration of Conformity",
      "mime_type": "application/pdf",
      "file_size": 184320,
      "upload_state": "ready",
      "uploaded_at": "2026-07-29T15:44:02.008Z",
      "livemode": true,
      "created_at": "2026-07-29T15:43:51.660Z",
      "linked_at": "2026-07-29T15:43:51.660Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

GET /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/documents?access_tier=public

Créer un document et obtenir une URL de téléversement signée.

post/organizations/{organization}/passports/{id}/documents

Portée: documents:write
Idempotency-Key: Accepté
Renvoie: 201

Paramètres de chemin

organizationstringObligatoire

L'organisation pour laquelle cette requête agit. La clé doit disposer d'une autorisation sur celle-ci.

idstringObligatoire

L'identifiant de la ressource. Traitez-le comme une chaîne opaque.

Corps de la requête

Ce point de terminaison accepte l'un des deux corps de requête. N'envoyez qu'une seule forme : un corps combinant les champs des deux est refusé.

Associer un document déjà présent dans la bibliothèque

document_idstringObligatoire

Lier un document déjà présent dans la bibliothèque de l'organisation plutôt que d'en téléverser un. Ne peut être combiné avec aucun des champs de téléversement. Lier un document qui ne l'est pas encore répond 201 ; le lier de nouveau alors qu'il l'est déjà répond 200. Aucune des deux réponses ne porte d'objet upload.

Téléverser un nouveau fichier

typestringObligatoire

Obligatoire lors d'un téléversement ; doit être absent lorsque document_id est renseigné. Au choix : certification, image, document, conformity_declaration.

access_tierstringObligatoire

Obligatoire lors d'un téléversement ; doit être absent lorsque document_id est renseigné. Au choix : public, restricted, authority. Ce niveau détermine qui pourra lire le fichier une fois le passeport en ligne.

file_namestringObligatoire

Obligatoire lors d'un téléversement ; doit être absent lorsque document_id est renseigné. Le nom sous lequel le fichier sera conservé.

mime_typestringObligatoire

Obligatoire lors d'un téléversement ; doit être absent lorsque document_id est renseigné. Au choix : application/pdf, image/png, image/jpeg, image/webp. Transmis tel quel au stockage, qui refuse toute discordance.

file_sizeintegerFacultatif

La taille en octets, jusqu'à 10485760.

display_namestringFacultatif

Le libellé que voit un lecteur. Par défaut, file_name.

Erreurs

Tous les refus que ce point de terminaison peut renvoyer, avec le statut qui les accompagne.

Requête

curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/documents" \
  -X POST \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "conformity_declaration",
  "access_tier": "public",
  "file_name": "doc-2026-kestrel.pdf",
  "mime_type": "application/pdf",
  "file_size": 184320,
  "display_name": "EU Declaration of Conformity"
}'

Réponse · 201

{
  "object": "document",
  "id": "a3b8c2d1-5e64-4f79-8a0b-1c2d3e4f5a6b",
  "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/documents/a3b8c2d1-5e64-4f79-8a0b-1c2d3e4f5a6b",
  "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
  "passport_id": "2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "passport": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "type": "conformity_declaration",
  "access_tier": "public",
  "file_name": "doc-2026-kestrel.pdf",
  "display_name": "EU Declaration of Conformity",
  "mime_type": "application/pdf",
  "file_size": 184320,
  "upload_state": "pending",
  "uploaded_at": null,
  "livemode": true,
  "created_at": "2026-08-02T09:40:12.331Z",
  "linked_at": "2026-08-02T09:40:12.331Z",
  "upload": {
    "url": "https://<project>.supabase.co/storage/v1/object/upload/sign/passport-assets/<organization>/library/<uuid>-doc-2026-kestrel.pdf?token=<jwt>",
    "method": "PUT",
    "headers": {
      "Content-Type": "application/pdf"
    },
    "expires_at": "2026-08-02T11:40:12.331Z",
    "max_bytes": 10485760
  }
}

POST /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/documents