Create patient refund

Beta

POST

/api/patient-refunds/v1

POST

/api/patient-refunds/v1

$ curl -X POST https://api.joincandidhealth.com/api/patient-refunds/v1 \
>      -H "Authorization: Bearer <token>" \
>      -H "Content-Type: application/json" \
>      -d '{
>   "amount_cents": 1,
>   "patient_external_id": "patient_external_id",
>   "allocations": [
>     {
>       "amount_cents": 1,
>       "target": {
>         "type": "service_line_by_id",
>         "value": "d5e9c84f-c2b2-4bf4-b4b0-7ffd7a9ffc32"
>       }
>     },
>     {
>       "amount_cents": 1,
>       "target": {
>         "type": "service_line_by_id",
>         "value": "d5e9c84f-c2b2-4bf4-b4b0-7ffd7a9ffc32"
>       }
>     }
>   ]
> }'

1 {
2   "patient_refund_id": "d5e9c84f-c2b2-4bf4-b4b0-7ffd7a9ffc32",
3   "organization_id": "d5e9c84f-c2b2-4bf4-b4b0-7ffd7a9ffc32",
4   "refund_source": "MANUAL_ENTRY",
5   "amount_cents": 1,
6   "patient_external_id": "patient_external_id",
7   "allocations": [
8     {
9       "amount_cents": 1,
10       "target": {
11         "type": "service_line",
12         "claim_id": "d5e9c84f-c2b2-4bf4-b4b0-7ffd7a9ffc32",
13         "encounter_id": "d5e9c84f-c2b2-4bf4-b4b0-7ffd7a9ffc32",
14         "service_line_id": "d5e9c84f-c2b2-4bf4-b4b0-7ffd7a9ffc32"
15       },
16       "allocation_id": "d5e9c84f-c2b2-4bf4-b4b0-7ffd7a9ffc32",
17       "earmark": {
18         "id": "d5e9c84f-c2b2-4bf4-b4b0-7ffd7a9ffc32",
19         "target": {
20           "type": "date_of_service",
21           "value": "target"
22         },
23         "amount_earmarked_cents": 1,
24         "created_by_allocation_id": "d5e9c84f-c2b2-4bf4-b4b0-7ffd7a9ffc32"
25       },
26       "allocated_on": "2024-01-15T09:30:00Z"
27     },
28     {
29       "amount_cents": 1,
30       "target": {
31         "type": "service_line",
32         "claim_id": "d5e9c84f-c2b2-4bf4-b4b0-7ffd7a9ffc32",
33         "encounter_id": "d5e9c84f-c2b2-4bf4-b4b0-7ffd7a9ffc32",
34         "service_line_id": "d5e9c84f-c2b2-4bf4-b4b0-7ffd7a9ffc32"
35       },
36       "allocation_id": "d5e9c84f-c2b2-4bf4-b4b0-7ffd7a9ffc32",
37       "earmark": {
38         "id": "d5e9c84f-c2b2-4bf4-b4b0-7ffd7a9ffc32",
39         "target": {
40           "type": "date_of_service",
41           "value": "target"
42         },
43         "amount_earmarked_cents": 1,
44         "created_by_allocation_id": "d5e9c84f-c2b2-4bf4-b4b0-7ffd7a9ffc32"
45       },
46       "allocated_on": "2024-01-15T09:30:00Z"
47     }
48   ],
49   "source_internal_id": "source_internal_id",
50   "refund_timestamp": "2024-01-15T09:30:00Z",
51   "refund_note": "refund_note",
52   "invoice": "d5e9c84f-c2b2-4bf4-b4b0-7ffd7a9ffc32",
53   "refund_reason": "OVERCHARGED"
54 }

Creates a new patient refund record and returns the newly created PatientRefund object. The allocations can describe whether the refund is being applied toward a specific service line, claim, or billing provider.

Authentication

AuthorizationBearer

OAuth authentication of the form <token>.

Request

This endpoint expects an object.

amount_centsintegerRequired

patient_external_idstringRequired

allocationslist of objectsRequired

refund_timestampdatetimeOptional

refund_notestringOptional

invoiceUUIDOptional

refund_reasonenumOptional

Allowed values:

allocation_restrictionslist of objectsOptional

Optional restrictions constraining which claims this refund’s credit can be auto-allocated to (e.g. billing provider NPI). Restriction (type, value) pairs must be unique. When omitted, the refund is unrestricted. Refunds created from an existing payment inherit that payment’s restrictions instead.

raise_on_overdraftbooleanOptional

If true, the refund will be rejected if it would cause any account to be overdrafted. Defaults to false.

Response

This endpoint returns an object.

patient_refund_idUUID

organization_idUUID

refund_sourceenum

amount_centsinteger

patient_external_idstring

allocationslist of objects

source_internal_idstring

refund_timestampdatetime

refund_notestring

invoiceUUID

refund_reasonenum

Errors

403

Unauthorized Error

404

Entity Not Found Error

422

Reallocation Would Overdraft Error

422

Unprocessable Entity Error