Create a new manual need

POST

/api/needs

curl --request POST \
  --url https://example.com/api/needs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "partnerId": "20000000-0000-0000-0000-000000000002", "status": "NEW", "customFields": { "dietaryRestrictions": "Gluten-Free", "urgency": "High" }, "isConfidential": false, "parentNeedId": "30000000-0000-0000-0000-000000000003", "assignedTo": "a1b2c3d4-e5f6-7890-abcd-1234567890ab", "constituentId": "40000000-0000-0000-0000-000000000004", "householdId": "50000000-0000-0000-0000-000000000005" }'

Authorizations

• BearerAuth

Request Body^required

Media typeapplication/json

object

partnerId

required

Unique identifier (UUID v4) for the assigned partner location facility.

string format: uuid

Example

20000000-0000-0000-0000-000000000002

status

Current status of the record or process.

string

Allowed values: NEW IN_PROGRESS PENDING_INTERNAL PENDING_CLIENT RESOLVED ESCALATED

customFields

Flexible key-value payload for partner-specific intake fields.

object

Example

{
  "dietaryRestrictions": "Gluten-Free",
  "urgency": "High"
}

isConfidential

Flag marking sensitive constituent request details as confidential.

boolean

Example

false

parentNeedId

UUID (v4) of parent need if part of a linked multi-step request.

string format: uuid

Example

30000000-0000-0000-0000-000000000003

assignedTo

UUID (v4) of the staff user assigned to handle the request.

string format: uuid

Example

a1b2c3d4-e5f6-7890-abcd-1234567890ab

constituentId

UUID (v4) of the constituent record.

string format: uuid

Example

40000000-0000-0000-0000-000000000004

householdId

UUID (v4) of the constituent household group.

string format: uuid

Example

50000000-0000-0000-0000-000000000005

Responses

201

Need created successfully

Media typeapplication/json

object

id

required

Unique identifier (UUID v4) for the resource.

string format: uuid

organizationId

required

Unique identifier (UUID v4) for the parent organization.

string format: uuid

partnerId

required

Unique identifier (UUID v4) for the assigned partner location facility.

string format: uuid

status

required

Current status of the record or process.

string

Allowed values: NEW IN_PROGRESS PENDING_INTERNAL PENDING_CLIENT RESOLVED ESCALATED

customFields

required

Flexible key-value payload for partner-specific intake fields.

object

isConfidential

required

Flag marking sensitive constituent request details as confidential.

boolean

parentNeedId

UUID (v4) of parent need if part of a linked multi-step request.

string format: uuid

assignedTo

UUID (v4) of the staff user assigned to handle the request.

string format: uuid

createdBy

UUID (v4) of the user or system process that created the record.

string format: uuid

createdAt

required

UTC ISO-8601 timestamp when the record was created.

string format: date-time

updatedAt

required

UTC ISO-8601 timestamp when the record was last updated.

string format: date-time

dueDate

Target resolution date and time for the request.

string format: date-time

constituentId

UUID (v4) of the constituent record.

string format: uuid

householdId

UUID (v4) of the constituent household group.

string format: uuid

duplicateWarning

Warning notice if potential constituent duplicate matches exist.

string

referenceNumber

Human-readable intake reference code.

string

Example

{
  "id": "a1b2c3d4-e5f6-7890-abcd-1234567890ab",
  "organizationId": "10000000-0000-0000-0000-000000000001",
  "partnerId": "20000000-0000-0000-0000-000000000002",
  "status": "NEW",
  "customFields": {
    "dietaryRestrictions": "Gluten-Free",
    "urgency": "High"
  },
  "isConfidential": false,
  "parentNeedId": "30000000-0000-0000-0000-000000000003",
  "assignedTo": "a1b2c3d4-e5f6-7890-abcd-1234567890ab",
  "createdBy": "a1b2c3d4-e5f6-7890-abcd-1234567890ab",
  "createdAt": "2026-07-28T12:00:00Z",
  "updatedAt": "2026-07-28T14:30:00Z",
  "dueDate": "2026-07-31T12:00:00Z",
  "constituentId": "40000000-0000-0000-0000-000000000004",
  "householdId": "50000000-0000-0000-0000-000000000005",
  "duplicateWarning": "Potential match detected: Sarah Jenkins (+17045550199)",
  "referenceNumber": "REQ-2026-0849"
}

401

Unauthorized

403

Forbidden