Technical Best Practices - Eulerian Marketing Platform API

1. Authentication & Security

API token

 Best practices:
Authorization: Bearer <votre_token_api>

• Never hardcode the token into the source code. Use an environment variable or a secrets vault (Vault, AWS Secrets Manager, etc.).
• Restrict tokens to strictly necessary permissions (principle of least privilege).
• Do not log authorization headers in application log files.

HTTPS required

2. General principles of integration

URL structure

 The domain is specific to your Eulerian account (e.g.
https://<votre_domaine_eulerian>/ea/v2/<endpoint>

Standard headers

 Content-Type: application/json
Accept: application/json
Rate limiting
Authorization: Bearer <token>



• Respect the speed limits imposed by Eulerian (refer to your contract documentation).
• Implement an exponential backoff mechanism in case of a 429 Too Many Requests response.
• Avoid excessive parallelization of calls: prefer ordered processing queues.

Idempotence

• For job creation requests, use a business identifier ( jobrun_id on the client side) to avoid duplicates in case of retry.
• Check for the existence of a similar job before creating a new one.

3. Batch Reporting — Overview

You submit a report request → Eulerian creates a job and returns a jobrun_id .
You periodically check the job status ( polling ).
Once the job is finished ( DONE ), you download the results file.

When to use Batch Reporting?

4. Batch Job Lifecycle

[SUBMIT]  →  PENDING  →  RUNNING  →  DONE
                                  ↘  FAILED
                                  ↘  EXPIRED


5. Polling & Status Management

Status endpoint

 Recommended polling strategy
GET /ea/v2/report/batch/status.json?jobrun-id={jobrun_id}



• Store the jobrun_id persistently (database, file) so that polling can resume after a restart of your application.
• Do not start a new job if an identical job is already in progress ( PENDING or RUNNING ).

Example of a polling loop (pseudocode)

ATTENDRE 30 secondes
TANT QUE timeout non atteint :
 statut = GET /batch/status.json?jobrun-id{jobrun_id}
 SI statut == DONE → télécharger résultat → FIN
 SI statut == FAILED → logger erreur → FIN
 SI statut == EXPIRED → relancer job → FIN
 ATTENDRE intervalle_adaptatif()
7. Retrieval and processing of results
SINON → alerter équipe ops 



Download endpoint

 The response contains either the file directly for streaming, or a temporary download URL.
GET /ea/v2/report/batch/download.json?jobrun-id={jobrun_id}

Downloading best practices

• Stream the download rather than loading the entire file into memory (files can reach several hundred MB).
• Archive the raw file before any processing (principle of idempotence of processing).

CSV processing

• Always specify UTF-8 encoding when opening the file.
• Manage header rows dynamically (columns can change).
• Verify the number of columns in each row before inserting into the database.
• Handle null values ​​/ empty strings explicitly (do not confuse them with 0 ).

Large Volume Management

• Process line by line in streaming (never load everything into RAM).
• Insert into the database in batches of 1,000 to 5,000 rows (bulk insert).
• Implement error recovery with marking of the last processed line.

8. Error Handling

HTTP codes to process

Retry strategy

 Tentative 1 : immédiate
Tentative 2 : +5 secondes
Tentative 3 : +15 secondes
Tentative 4 : +60 secondes
Tentative 5 : +300 secondes
Never retry on mistakes
Au-delà : alerter et abandonner

Logging

• Logger systematically: timestamp, endpoint called, HTTP code received, job_id , duration of the request.
• Never log the API token or end-user personal data.
• Keep error logs for at least 30 days to facilitate debugging.

9. Production Deployment Checklist

Security

• API token stored in an environment variable (never hardcoded in the code)
• HTTPS forced on all calls
• Logs do not contain the token or personal data

Robustness

• Retry with exponential backoff implemented
• Global timeout on the defined polling (recommended: 4 hours)
• jobrun_id persisted for recovery after crash
• Checking the status before restarting the same job

Performance

• Date ranges divided into windows ≤ 90 days
• Column selection limited to the bare minimum
• Streaming download (no full memory loading)
• Insertion into database in batches (bulk insert)

Monitoring

• Alerts about jobs that FAILED or KILLED
• Error alerts for 401 / 403 (expired token)
• Job processing time tracking dashboard
• Archiving raw files before processing

Tests

• Tests with short date ranges before going into production
• Validation of the output CSV format (number of columns, encoding)
• Testing behavior in the event of a 429 (rate limiting)
• Resumption test after interruption during polling