Proposals — PassportCraft API

Propose changes to a published passport.

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

Scope: passports:write
Idempotency-Key: Accepted
Returns: 201

Path parameters

organizationstringRequired

The organization this request acts for. The credential must hold a grant for it.

idstringRequired

The identifier of the resource. Treat it as an opaque string.

Request body

fieldsobjectRequired

The fields to change, in the shape a passport update takes. Send a number together with its unit. A null removes a value.

Errors

Every refusal this endpoint can return, with the status it arrives with.

Request

curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/proposals" \
  -X POST \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "fields": {
    "recycled_content_percentage": 42
  }
}'

Response · 201

{
  "object": "passport_proposal",
  "id": "9e2c4a71-3f68-4d05-8a9b-7c1e5f0d2b63",
  "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/proposals/9e2c4a71-3f68-4d05-8a9b-7c1e5f0d2b63",
  "passport_id": "2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "state": "pending",
  "moved": [],
  "fields": {
    "recycled_content_percentage": 42
  },
  "review_url": "https://passportcraft.com/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/edit?proposal=9e2c4a71-3f68-4d05-8a9b-7c1e5f0d2b63",
  "requested_at": "2026-09-26T10:00:00.000Z",
  "expires_at": "2026-10-03T10:00:00.000Z",
  "decided_at": null,
  "livemode": true
}

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

Fetch one proposal.

get/organizations/{organization}/proposals/{id}

Scope: passports:read
Idempotency-Key: Not accepted
Returns: 200

Path parameters

organizationstringRequired

The organization this request acts for. The credential must hold a grant for it.

idstringRequired

The identifier of the resource. Treat it as an opaque string.

Errors

Every refusal this endpoint can return, with the status it arrives with.

Request

curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/proposals/9e2c4a71-3f68-4d05-8a9b-7c1e5f0d2b63" \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY"

Response · 200

{
  "object": "passport_proposal",
  "id": "9e2c4a71-3f68-4d05-8a9b-7c1e5f0d2b63",
  "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/proposals/9e2c4a71-3f68-4d05-8a9b-7c1e5f0d2b63",
  "passport_id": "2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "state": "out_of_date",
  "moved": [
    "recycled_content_percentage"
  ],
  "fields": {
    "recycled_content_percentage": 42
  },
  "review_url": "https://passportcraft.com/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/edit?proposal=9e2c4a71-3f68-4d05-8a9b-7c1e5f0d2b63",
  "requested_at": "2026-09-26T10:00:00.000Z",
  "expires_at": "2026-10-03T10:00:00.000Z",
  "decided_at": null,
  "livemode": true
}

GET /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/proposals/9e2c4a71-3f68-4d05-8a9b-7c1e5f0d2b63

Withdraw a waiting proposal.

post/organizations/{organization}/proposals/{id}/withdraw

Scope: passports:write
Idempotency-Key: Accepted
Returns: 200

Path parameters

organizationstringRequired

The organization this request acts for. The credential must hold a grant for it.

idstringRequired

The identifier of the resource. Treat it as an opaque string.

Errors

Every refusal this endpoint can return, with the status it arrives with.

Request

curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/proposals/9e2c4a71-3f68-4d05-8a9b-7c1e5f0d2b63/withdraw" \
  -X POST \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Response · 200

{
  "object": "passport_proposal",
  "id": "9e2c4a71-3f68-4d05-8a9b-7c1e5f0d2b63",
  "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/proposals/9e2c4a71-3f68-4d05-8a9b-7c1e5f0d2b63",
  "passport_id": "2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "state": "withdrawn",
  "moved": [],
  "fields": {
    "recycled_content_percentage": 42
  },
  "review_url": "https://passportcraft.com/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/edit?proposal=9e2c4a71-3f68-4d05-8a9b-7c1e5f0d2b63",
  "requested_at": "2026-09-26T10:00:00.000Z",
  "expires_at": "2026-10-03T10:00:00.000Z",
  "decided_at": "2026-09-26T11:00:00.000Z",
  "livemode": true
}

POST /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/proposals/9e2c4a71-3f68-4d05-8a9b-7c1e5f0d2b63/withdraw