Signature
Compute the expected HMAC from the timestamp and raw request body using the active webhook secret.
Static developer documentation
Enrich API Documentation and Quickstart
Use this reference to design the request contract, authentication, schemas, errors and asynchronous job behavior for an AI enrichment service.
QuickstartAuthenticationSchemasWebhooks
Implementation status
This documentation is part of a static launch site. Requests and responses are illustrative until a real EnrichAPI.com backend, authentication layer and provider adapters are deployed.
Quickstart
Create one synchronous enrichment request
Send a JSON object, list the enrichments you want and select a versioned output schema.
curl --request POST \
--url https://api.enrichapi.com/v1/enrich \
--header "Authorization: Bearer $ENRICH_API_KEY" \
--header "Content-Type: application/json" \
--header "Idempotency-Key: company-example-001" \
--data '{
"input": {
"company": "Example Robotics",
"website": "example.com"
},
"enrichments": [
"company_summary",
"industry",
"location",
"semantic_tags"
],
"schema": "company_profile_v1"
}' {
"request_id": "req_01JEXAMPLE",
"status": "completed",
"data": {
"company_name": "Example Robotics",
"industry": "Industrial automation",
"summary": "Software for warehouse robotics and fleet operations.",
"location": {
"city": "San Francisco",
"country": "United States"
},
"semantic_tags": ["robotics", "warehouse-ai", "fleet-operations"]
},
"validation": {
"schema": "company_profile_v1",
"valid": true,
"warnings": []
},
"usage": {
"route": "balanced",
"attempts": 1
}
}Authentication
Use scoped bearer keys from a protected server
Production keys must never appear in this static site or any browser-delivered JavaScript.
Authorization header
Send the key as Authorization: Bearer $ENRICH_API_KEY. Reject keys in query strings because URLs often appear in logs and analytics.
Environment separation
Use different keys for local development, staging and production. Scope each key to approved endpoint groups, schemas and account limits.
Rotation
Allow overlapping active keys during rotation, record the key identifier on each request and revoke compromised keys immediately.
Browser safety
A static website cannot safely hold a private API key. Create a protected server endpoint or edge worker that authenticates the user and calls the Enrich API on their behalf.
Endpoints
Use synchronous requests for small jobs and queued jobs for batches
The endpoint set stays small so client behavior remains easy to understand.
| Endpoint | Request | Response | Notes |
|---|---|---|---|
POST /v1/enrich | One input object and enrichment list | Completed data or controlled error | Use for bounded interactive jobs |
POST /v1/enrich/batch | Array, file reference or data source | Accepted job identifier | Use idempotency and a completion webhook |
GET /v1/jobs/{id} | Job identifier | Status, progress and result location | Poll with backoff when webhooks are unavailable |
GET /v1/schemas | Optional type filter | Available schema versions | Cache and pin a version in clients |
POST /v1/validate | Schema name and candidate object | Field-level validation result | Useful for imported or repaired records |
Schemas
Define structured JSON before the enrichment runs
A schema makes the expected output testable and gives every provider route the same target contract.
{
"$id": "company_profile_v1",
"type": "object",
"additionalProperties": false,
"required": ["company_name", "summary", "semantic_tags"],
"properties": {
"company_name": {"type": "string", "minLength": 1},
"industry": {"type": ["string", "null"]},
"summary": {"type": "string", "maxLength": 320},
"location": {
"type": "object",
"required": ["city", "country"],
"properties": {
"city": {"type": ["string", "null"]},
"country": {"type": ["string", "null"]}
}
},
"semantic_tags": {
"type": "array",
"maxItems": 12,
"items": {"type": "string"}
}
}
}Version schemas deliberately
Keep a schema stable once clients depend on it. Add compatible optional fields cautiously and create a new version for renamed fields, type changes or new required properties.
Allow honest unknowns
Use nullable fields for values the pipeline may not know. A null value is better than an invented answer that appears valid.
Reject extra properties
Set additionalProperties to false when your application needs a strict contract. Unexpected output can then trigger repair or review rather than silently entering storage.
See the structured JSON validation guide for a deeper implementation pattern.
Errors
Return a stable code, useful message and retry guidance
Clients should not need to parse provider text or guess whether a failure is safe to retry.
| HTTP | Error code | Meaning | Retry? |
|---|---|---|---|
| 400 | invalid_request | Missing or malformed input. | No; fix the request. |
| 401 | invalid_api_key | Key is missing, revoked or malformed. | No; replace credentials. |
| 409 | idempotency_conflict | The same key was used for different content. | No; use the original body or a new key. |
| 422 | schema_invalid | The result could not satisfy the required schema. | Maybe; follow repair guidance. |
| 429 | rate_limited | The account or route limit was reached. | Yes; honor the reset header. |
| 503 | provider_unavailable | No allowed route completed the task. | Yes; use backoff within the deadline. |
Webhooks
Verify every asynchronous completion event
A signed webhook can deliver batch status without continuous polling. Treat the payload as untrusted until the signature is verified.
Replay protection
Reject stale timestamps and store delivery identifiers so the same event cannot be processed twice.
Retry handling
Return a successful status only after the event is safely queued. Make event processing idempotent.
Security checklist
Protect secrets, data and downstream writes
Use this baseline before sending real customer data to an enrichment pipeline.
- Store API keys in a secret manager.
- Send only fields the selected enrichment requires.
- Redact sensitive content from logs.
- Use TLS and verify certificates.
- Scope keys by environment and operation.
- Record schema and request identifiers.
- Validate every output before storage.
- Require review for low-confidence high-impact fields.
- Sign and verify webhook deliveries.
- Define retention and deletion behavior.
- Test provider fallback data policies.
- Maintain key revocation and incident procedures.
Documentation FAQ
Clarify the static reference before implementation
These answers separate the website specification from the backend that still needs to be deployed.
Is this documentation connected to a live API?
No. This package is a static website and documentation reference. The examples define an intended interface that must be implemented behind a real endpoint before production.
What is the base URL shown in examples?
The examples use https://api.enrichapi.com/v1 as the intended production base URL. Confirm DNS, TLS, routing and backend availability before publishing it as live.
How are schemas versioned?
Use stable schema names with explicit versions such as company_profile_v1. Add fields compatibly or release a new version when a change can break clients.
How do asynchronous jobs notify clients?
The reference pattern creates a job, exposes a status endpoint and optionally sends a signed webhook when processing finishes.
Where are provider-specific settings configured?
Keep them inside a routing object or server-side account policy. The normalized response schema should remain provider-independent.
Turn the reference into a working service
Implement authentication, endpoint logic, provider adapters, schema validation, observability and billing behind the static developer experience.