Create patient payment

Beta

POST

/api/patient-payments/v4

POST

/api/patient-payments/v4

$ curl -X POST https://api.joincandidhealth.com/api/patient-payments/v4 \
>      -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_payment_id": "d5e9c84f-c2b2-4bf4-b4b0-7ffd7a9ffc32",
3   "organization_id": "d5e9c84f-c2b2-4bf4-b4b0-7ffd7a9ffc32",
4   "payment_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   "payment_timestamp": "2024-01-15T09:30:00Z",
51   "payment_note": "payment_note",
52   "invoice": "d5e9c84f-c2b2-4bf4-b4b0-7ffd7a9ffc32",
53   "payment_method_detail": {
54     "payment_method": {
55       "type": "cash"
56     },
57     "collected_at_address": {
58       "address1": "address1",
59       "city": "city",
60       "state": "AA",
61       "zip_code": "zip_code",
62       "address2": "address2",
63       "zip_plus_four_code": "zip_plus_four_code"
64     },
65     "provider_info": {
66       "npi": "npi",
67       "first_name": "first_name",
68       "last_name": "last_name"
69     }
70   }
71 }

Creates a new patient payment record and returns the newly created PatientPayment object. The allocations can describe whether the payment 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

payment_timestampdatetimeOptional

payment_notestringOptional

invoiceUUIDOptional

payment_method_detailobjectOptional

payment_sourceenumOptional

Allowed payment sources when creating a patient payment via the API.

Allowed values:

source_internal_idstringOptional

allocation_restrictionslist of objectsOptional

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

Response

This endpoint returns an object.

patient_payment_idUUID

organization_idUUID

payment_sourceenum

amount_centsinteger

patient_external_idstring

allocationslist of objects

source_internal_idstring

payment_timestampdatetime

payment_notestring

invoiceUUID

payment_method_detailobject

Errors

403

Unauthorized Error

404

Entity Not Found Error

422

Unprocessable Entity Error