REST API

API documentation

Build PDF stamping into your applications with our simple, powerful REST API

Quick start

Start using the API in three simple steps

Create an account

Generate an API key

From your dashboard, create a secure API key

Make your first call

Use the API to stamp your PDFs

Authentication

Every API request requires an authentication key

Get an API key

Sign in to your HelloStampPdf account
Go to the API keys section
Click Create an API key
Give the key a name and copy it — it is shown only once

Required authentication header

Authorization: Bearer YOUR_API_KEY

Security

Never share your API key. Store it securely in your environment variables.

POST

/api/v1/stamp

Stamp one or more PDFs with a custom configuration

Parameters (multipart/form-data)

Requiredfiles

One or more PDF files, up to 20 files of 50 MB each

Requiredconfig(JSON string)

Stamp configuration

{
  "shape": "RECTANGLE",        // ROUND, SQUARE, RECTANGLE
  "position": "TOP_RIGHT",     // Voir positions ci-dessous
  "topText": "PIECE N°",       // Texte superieur
  "bottomText": "Dossier X",   // Texte inferieur (optionnel)
  "fontSize": 12,              // 6-24
  "color": "#000000",          // Couleur texte (hex)
  "startNumber": 1,            // Numero de depart
  "width": 120,                // 50-300 points
  "height": 60,                // 30-200 points
  "marginX": 20,               // 0-100 points
  "marginY": 20,               // 0-100 points
  "borderWidth": 2,            // 0-10 points
  "borderColor": "#000000",    // Couleur bordure (hex)
  "stampEffect": false         // Effet tampon (true/false)
}

Available positions:

TOP_LEFT

TOP_CENTER

TOP_RIGHT

CENTER_LEFT

CENTER

CENTER_RIGHT

BOTTOM_LEFT

BOTTOM_CENTER

BOTTOM_RIGHT

OptionaloutputType

MERGED (default) or SEPARATE

OptionalincludeBordereau

true or false (default: false)

OptionalcaseTitle

Case title used in the index

curl example

curl -X POST https://hellostamppdf.com/api/v1/stamp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "files=@document1.pdf" \
  -F "files=@document2.pdf" \
  -F 'config={"shape":"RECTANGLE","position":"TOP_RIGHT","topText":"PIECE N°","bottomText":"Affaire Martin","fontSize":12,"color":"#000000","startNumber":1,"width":120,"height":60,"marginX":20,"marginY":20,"borderWidth":2,"borderColor":"#000000","stampEffect":false}' \
  -F "outputType=MERGED" \
  -F "includeBordereau=true" \
  -F "caseTitle=Dossier Martin c/ Dupont"

Response (200 OK)

{
  "success": true,
  "jobId": "clxxx...",
  "totalPages": 10,
  "creditsUsed": 11,
  "creditsRemaining": 89,
  "processingTime": 1234,
  "files": [
    {
      "name": "stamped_merged.pdf",
      "data": "base64_encoded_pdf..."
    }
  ]
}

Output options and index

Choose how to receive your stamped PDFs and whether you want the summary index

MERGEDMerged PDF

All stamped PDFs are merged into a single file

✓ A single file to download

✓ Ideal for archiving

✓ Ready to print

SEPARATESeparate PDFs

Each exhibit is returned as its own PDF file

✓ Individual files

✓ Explicit file names (P1_, P2_ and so on)

✓ More flexibility

📋 Summary index

Add includeBordereau=true to automatically receive a PDF index listing all your exhibits.

• The index is always returned as a separate file

• It contains the number, name and page count of each exhibit

• It costs one extra credit

Example: separate PDFs with index

curl -X POST https://hellostamppdf.com/api/v1/stamp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "files=@contrat.pdf" \
  -F "files=@annexe.pdf" \
  -F "files=@conditions.pdf" \
  -F 'config={"shape":"ROUND","position":"TOP_RIGHT","topText":"PIECE N°","bottomText":"Cabinet Martin","fontSize":12,"color":"#dc2626","startNumber":1,"width":100,"height":100,"marginX":20,"marginY":20,"borderWidth":2,"borderColor":"#dc2626","stampEffect":true}' \
  -F "outputType=SEPARATE" \
  -F "includeBordereau=true" \
  -F "caseTitle=Affaire Martin c/ Dupont - TGI Paris"

Response with SEPARATE and index

{
  "success": true,
  "jobId": "clxxx...",
  "totalPages": 20,
  "creditsUsed": 21,  // 20 pages + 1 bordereau
  "creditsRemaining": 79,
  "processingTime": 2456,
  "files": [
    {
      "name": "P1_contrat.pdf",
      "data": "base64_encoded_pdf..."
    },
    {
      "name": "P2_annexe.pdf",
      "data": "base64_encoded_pdf..."
    },
    {
      "name": "P3_conditions.pdf",
      "data": "base64_encoded_pdf..."
    },
    {
      "name": "bordereau.pdf",
      "data": "base64_encoded_pdf..."
    }
  ]
}

Example: merged PDF with index

curl -X POST https://hellostamppdf.com/api/v1/stamp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "files=@contrat.pdf" \
  -F "files=@annexe.pdf" \
  -F "files=@conditions.pdf" \
  -F 'config={"shape":"RECTANGLE","position":"TOP_RIGHT","topText":"PIECE N°","fontSize":12,"color":"#000000","startNumber":1,"width":120,"height":60,"marginX":20,"marginY":20,"borderWidth":2,"borderColor":"#000000","stampEffect":false}' \
  -F "outputType=MERGED" \
  -F "includeBordereau=true" \
  -F "caseTitle=Affaire Martin c/ Dupont"

Response with MERGED and index

{
  "success": true,
  "jobId": "clxxx...",
  "totalPages": 20,
  "creditsUsed": 21,  // 20 pages + 1 bordereau
  "creditsRemaining": 79,
  "processingTime": 2123,
  "files": [
    {
      "name": "stamped_merged.pdf",      // Toutes les pieces fusionnees
      "data": "base64_encoded_pdf..."
    },
    {
      "name": "bordereau.pdf",           // Bordereau separe
      "data": "base64_encoded_pdf..."
    }
  ]
}

POST /api/v1/bordereau — generate the index only

Generates a PDF index without stamping any file, useful for separated workflows

💡 Use case

This endpoint is designed for applications that stamp PDFs locally and only need the summary index. Useful for working around payload size limits.

Request parameters (application/json)

pieces (required)

Array of exhibits to include in the index

[
  {
    "number": 1,        // Numero de la piece
    "name": "Contrat",  // Nom de la piece
    "pageCount": 5      // Nombre de pages
  },
  {
    "number": 2,
    "name": "Annexe A",
    "pageCount": 3
  }
]

caseTitle (optional)

Case title shown in the index

Example request

curl -X POST https://hellostamppdf.com/api/v1/bordereau \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pieces": [
      { "number": 1, "name": "Contrat de vente", "pageCount": 5 },
      { "number": 2, "name": "Annexe financiere", "pageCount": 3 },
      { "number": 3, "name": "Conditions generales", "pageCount": 12 }
    ],
    "caseTitle": "Affaire Martin c/ Dupont - TGI Paris"
  }'

Response (200 OK)

{
  "success": true,
  "creditsUsed": 1,
  "creditsRemaining": 99,
  "processingTime": 234,
  "file": {
    "name": "bordereau.pdf",
    "data": "base64_encoded_pdf..."
  }
}

⚠️ Important

• This endpoint stamps nothing, it only generates the index
• It costs one credit, for the index
• No PDF file is sent in the request, only the metadata
• The index is returned as a base64-encoded PDF

HTTP error codes

400Invalid request: missing or incorrect parameters

401Not authenticated: missing or invalid API key

402Insufficient credits

413File too large: 50 MB maximum per file

500Internal server error

Limits and quotas

File size

• 50 MB maximum per PDF file
• 20 files maximum per request

Rate limiting

• 60 requests per minute
• 1,000 requests per day

Ready to start?

Create a free account and receive 10 credits to try the API

Create a free account Contact us