Subsidies · Compense Docs

This page is generated from the contract (data/gateway-v1.json): each operation shows its verb, path, parameters, body, responses, whether it carries an Idempotency-Key, and the equivalent method in all five SDKs. For the end-to-end flow with complete examples, see the implementation guide.

Operations in tag `subsidies` #

Contract description: Statutory subsidy intake and decisioning (unemployment, housing, …).

Method	Path	Operation	Scope	Idem.
GET	`/v1/gateway/subsidies/applications/`	Subsidy application inbox	`subsidies:read`	—
GET	`/v1/gateway/subsidies/applications/{app_id}/`	Subsidy application detail	`subsidies:read`	—
POST	`/v1/gateway/subsidies/applications/{app_id}/decision/`	Decide a subsidy	`subsidies:decide`	recommended
POST	`/v1/gateway/subsidies/{subsidy_type}/`	Submit a subsidy (unemployment, housing, …)	`subsidies:submit`	recommended

Subsidy application inbox #

GET/v1/gateway/subsidies/applications/

operationId listSubsidyApplications
Authentication X-API-Key · scope subsidies:read
Idempotency-Key not applicable

Parameters

Name	In	Type
`page`	query	integer
`page_size`	query	integer
`search`	query	string
`status`	query	string

Responses

Code	Description	Body
200	Paginated subsidy applications.	`Page` application/json

Possible errors (400, 401, 403, 404, 409, 422, 429, 500, 502) — application/problem+json

400	Malformed request.	`about:blank`
401	Missing or invalid API key.	`about:blank`
403	The key is valid but lacks the required scope, or the source IP is not allow-listed.	`about:blank`
404	The requested resource does not exist.	`about:blank`
409	Idempotency conflict — same key, original still processing.	`https://errors.compense.co/gateway/idempotency-conflict`
422	Request body failed validation.	`https://errors.compense.co/gateway/validation`
429	Per-key rate limit or monthly quota exceeded; see `Retry-After`.	`https://errors.compense.co/gateway/rate-limited`
500	Unexpected gateway error; quote the `trace_id` to support.	`about:blank`
502	The processing engine returned an error.	`https://errors.compense.co/gateway/upstream-error`

See problem+json errors for the equivalent exception in each SDK.

Example

SDK method and HTTP request

client.subsidies.list_applications()

client.subsidies.listApplications()

$client->subsidies->listApplications()

await client.Subsidies.ListApplicationsAsync()

client.Subsidies.ListApplications(ctx, …)

curl "https://sandbox.dev.compense.co/gw/v1/gateway/subsidies/applications/" \
  -H "X-API-Key: $COMPENSE_API_KEY"

Each SDK's methods come from its contract parity suite. The cURL runs against the sandbox; <field> values are placeholders.

Subsidy application detail #

GET/v1/gateway/subsidies/applications/{app_id}/

operationId getSubsidyApplication
Authentication X-API-Key · scope subsidies:read
Idempotency-Key not applicable

Parameters

Name	In	Type	Description
`app_id` required	path	string	Subsidy application id. E.g.: `SUB-2026-000045`

Responses

Code	Description	Body
200	Subsidy application detail.	object application/json

Possible errors (400, 401, 403, 404, 409, 422, 429, 500, 502, 504) — application/problem+json

400	Malformed request.	`about:blank`
401	Missing or invalid API key.	`about:blank`
403	The key is valid but lacks the required scope, or the source IP is not allow-listed.	`about:blank`
404	The requested resource does not exist.	`about:blank`
409	Idempotency conflict — same key, original still processing.	`https://errors.compense.co/gateway/idempotency-conflict`
422	Request body failed validation.	`https://errors.compense.co/gateway/validation`
429	Per-key rate limit or monthly quota exceeded; see `Retry-After`.	`https://errors.compense.co/gateway/rate-limited`
500	Unexpected gateway error; quote the `trace_id` to support.	`about:blank`
502	The processing engine returned an error.	`https://errors.compense.co/gateway/upstream-error`
504	The processing engine did not respond in time.	`https://errors.compense.co/gateway/upstream-error`

See problem+json errors for the equivalent exception in each SDK.

Example

SDK method and HTTP request

client.subsidies.get_application()

client.subsidies.getApplication()

$client->subsidies->getApplication()

await client.Subsidies.GetApplicationAsync()

client.Subsidies.GetApplication(ctx, …)

curl "https://sandbox.dev.compense.co/gw/v1/gateway/subsidies/applications/SUB-2026-000045/" \
  -H "X-API-Key: $COMPENSE_API_KEY"

Each SDK's methods come from its contract parity suite. The cURL runs against the sandbox; <field> values are placeholders.

Decide a subsidy #

POST/v1/gateway/subsidies/applications/{app_id}/decision/

operationId decideSubsidyApplication
Authentication X-API-Key · scope subsidies:decide
Idempotency-Key recommended (the SDK generates it)

Parameters

Name	In	Type	Description
`app_id` required	path	string	Subsidy application id. E.g.: `SUB-2026-000045`
`Idempotency-Key`	header	string	Client-generated key that makes a write safely retryable. Replaying the same key returns the original result with `idempotent_replay: true`; a replay while the original is still in flight returns 409. E.g.: `horizonte-2026-06-26-credit-000123`

Request body

Content type: application/json · required

Schema SubsidyDecisionIn

Field	Type	Description
`decision` required	string	Values: `APPROVE`, `REJECT`. E.g.: `"APPROVE"`
`reason`	string (nullable)	E.g.: `"Cumple requisitos de permanencia."`

Accepts additional fields (additionalProperties): they're forwarded to the engine unchanged.

Responses

Code	Description	Body
200	Accepted; transaction enqueued / processed.	`TransactionEnvelope` application/json

Possible errors (400, 401, 403, 404, 409, 422, 429, 500, 502, 504) — application/problem+json

400	Malformed request.	`about:blank`
401	Missing or invalid API key.	`about:blank`
403	The key is valid but lacks the required scope, or the source IP is not allow-listed.	`about:blank`
404	The requested resource does not exist.	`about:blank`
409	Idempotency conflict — same key, original still processing.	`https://errors.compense.co/gateway/idempotency-conflict`
422	Request body failed validation.	`https://errors.compense.co/gateway/validation`
429	Per-key rate limit or monthly quota exceeded; see `Retry-After`.	`https://errors.compense.co/gateway/rate-limited`
500	Unexpected gateway error; quote the `trace_id` to support.	`about:blank`
502	The processing engine returned an error.	`https://errors.compense.co/gateway/upstream-error`
504	The processing engine did not respond in time.	`https://errors.compense.co/gateway/upstream-error`

See problem+json errors for the equivalent exception in each SDK.

Example

SDK method and HTTP request

client.subsidies.decide_application()

client.subsidies.decideApplication()

$client->subsidies->decideApplication()

await client.Subsidies.DecideApplicationAsync()

client.Subsidies.DecideApplication(ctx, …)

curl -X POST "https://sandbox.dev.compense.co/gw/v1/gateway/subsidies/applications/SUB-2026-000045/decision/" \
  -H "X-API-Key: $COMPENSE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "decision": "APPROVE",
    "reason": "Cumple requisitos de permanencia."
  }'

Each SDK's methods come from its contract parity suite. The cURL runs against the sandbox; <field> values are placeholders.

Submit a subsidy (unemployment, housing, …) #

POST/v1/gateway/subsidies/{subsidy_type}/

operationId submitSubsidyApplication
Authentication X-API-Key · scope subsidies:submit
Idempotency-Key recommended (the SDK generates it)

Parameters

Name	In	Type	Description
`subsidy_type` required	path	string	Subsidy type slug. E.g.: `unemployment`
`Idempotency-Key`	header	string	Client-generated key that makes a write safely retryable. Replaying the same key returns the original result with `idempotent_replay: true`; a replay while the original is still in flight returns 409. E.g.: `horizonte-2026-06-26-credit-000123`

Request body

Content type: application/json · required

Schema SubsidyApplicationIn — Statutory subsidy application. subsidy_type is the path segment (e.g. unemployment).

Field	Type	Description
`afiliado` required	`AffiliateRef`
`external_reference`	string	E.g.: `"HORIZONTE-SUB-2026-000045"`
`period`	string	Settlement period YYYY-MM. E.g.: `"2026-06"`

Accepts additional fields (additionalProperties): they're forwarded to the engine unchanged.

Responses

Code	Description	Body
200	Accepted; transaction enqueued / processed.	`TransactionEnvelope` application/json

Possible errors (400, 401, 403, 404, 409, 422, 429, 500, 502, 504) — application/problem+json

400	Malformed request.	`about:blank`
401	Missing or invalid API key.	`about:blank`
403	The key is valid but lacks the required scope, or the source IP is not allow-listed.	`about:blank`
404	The requested resource does not exist.	`about:blank`
409	Idempotency conflict — same key, original still processing.	`https://errors.compense.co/gateway/idempotency-conflict`
422	Request body failed validation.	`https://errors.compense.co/gateway/validation`
429	Per-key rate limit or monthly quota exceeded; see `Retry-After`.	`https://errors.compense.co/gateway/rate-limited`
500	Unexpected gateway error; quote the `trace_id` to support.	`about:blank`
502	The processing engine returned an error.	`https://errors.compense.co/gateway/upstream-error`
504	The processing engine did not respond in time.	`https://errors.compense.co/gateway/upstream-error`

See problem+json errors for the equivalent exception in each SDK.

Example

SDK method and HTTP request

client.subsidies.submit_application()

client.subsidies.submitApplication()

$client->subsidies->submitApplication()

await client.Subsidies.SubmitApplicationAsync()

client.Subsidies.SubmitApplication(ctx, …)

curl -X POST "https://sandbox.dev.compense.co/gw/v1/gateway/subsidies/unemployment/" \
  -H "X-API-Key: $COMPENSE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "afiliado": {
      "document_type": "CC",
      "document_number": "1032456789"
    },
    "period": "2026-06",
    "external_reference": "HORIZONTE-SUB-2026-000045"
  }'

Each SDK's methods come from its contract parity suite. The cURL runs against the sandbox; <field> values are placeholders.

Operations in tag subsidies #

Subsidy application inbox #

Parameters

Responses

Example

Subsidy application detail #

Parameters

Responses

Example

Decide a subsidy #

Parameters

Request body

Responses

Example

Submit a subsidy (unemployment, housing, …) #

Parameters

Request body

Responses

Example

Operations in tag `subsidies` #