SPEAR API Docs

Client API

/client/: Clients / Prospective Clients

CRUD operations for client objects supported via ModelViewSet APIs.

Example Objects

{
    "id": 1,
    "name": "Test Client",
    "is_active": true
}

/client-contact/: Client Contacts

CRUD operations for client objects supported via ModelViewSet APIs.

This API supports filtering and searching the list of contacts.

Note: This API uses a different format for Client Contact object responses and requests.

Filtering

When listing client contacts with GET /client-contact/, you can use the following query parameters to filter results:

Query Parameter Description
client_id Filter by client ID
program_location_id Filter by program location ID
is_program_contact Filter by program contact status, accepts true or false
is_prospective_client Filter by prospective client status, accepts true or false

Filters can be combined. For example: GET /client-contact/?client_id=1&is_program_contact=true

The search functionality allows you to search by first name, last name, or email address using prefix matching.

Query Parameter Description
search Returns all client contacts where the first name, last name, or email starts with the search term

Search can be combined with filters: GET /client-contact/?search=Gabriel&client_id=1

Example Response Objects

client_info, user_info, and programs are only present on responses and should not be used when making create/update requests.

{
    "id": 1234,
    "client_info": {
        "id": 1,
        "name": "Test Client",
        "is_active": true
    },
    "first_name": "Gabriel",
    "middle_name": "Sebastean",
    "last_name": "Pulido",
    "title": "Software Developer",
    "dob": "2000-01-01",
    "email": "gabriel@arguswest.com",
    "work_phone": null,
    "mobile_phone": "(619)555-5555",
    "general_note": "Test",
    "is_active": true,
    "user_info": {
        "id": 123,
        "username": "mirainuko"
    },
    "programs": [
        {
            "id": 12,
            "program": {
                "id": 23,
                "name": "Program Name"
            },
            "title": "Director",
            "start_date": "2020-01-01",
            "end_date": "2023-07-01",
            "is_active": true
        }
    ],
}

Example Request Objects

Instead of client_info and user_info, instead specify their IDs directly on the client and user fields.

For programs, use the assign_programs list with a list of IDs to set the programs a client contact is a part of.

Just like other ModelViewSet-based APIs, omit the id when creating new objects.

{
    "id": 1234,
    "client": 1,
    "first_name": "Gabriel",
    "middle_name": "Sebastean",
    "last_name": "Pulido",
    "title": "Software Developer",
    "dob": "2000-01-01",
    "email": "gabriel@arguswest.com",
    "work_phone": null,
    "mobile_phone": "(619)555-5555",
    "general_note": "Test",
    "is_active": true,
    "user": 123,
    "assign_programs": [12]
}

/program-location/: Program Locations

CRUD operations for program location objects supported via ModelViewSet APIs.

This API supports filtering and searching the list of program locations.

Note: This API uses a different format for Program Location object responses and requests.

Filtering

When listing program locations with GET /program-location/, you can use the following query parameter to filter results:

Query Parameter Description
client_id Filter by client ID

Search

The search functionality allows you to search by program name or physical city using prefix matching.

Query Parameter Description
search Returns all program locations where the program name or physical city starts with the search term

Search can be combined with filters: GET /program-location/?search=Downtown&client_id=1

Example Response Objects

client_info is only present on responses and should not be used when making create/update requests.

{
    "id": 23,
    "client_info": {
        "id": 1,
        "name": "Test Client",
        "is_active": true
    },
    "program_name": "Downtown Program",
    "physical_address_1": "123 Main St",
    "physical_address_2": "Suite 100",
    "physical_address_3": null,
    "physical_city": "San Diego",
    "physical_state": "CA",
    "physical_zip": "92101",
    "mailing_address_1": "PO Box 456",
    "mailing_address_2": null,
    "mailing_address_3": null,
    "mailing_city": "San Diego",
    "mailing_state": "CA",
    "mailing_zip": "92102",
    "primary_phone": "(619)555-1234",
    "primary_email": "contact@program.com",
    "billing_email": "billing@program.com",
    "client_instructions": "Special instructions for client",
    "invoice_instructions": "Net 30",
    "general_notes": "Additional notes",
    "is_active": true
}

Example Request Objects

Instead of client_info, specify the client ID directly on the client field.

Just like other ModelViewSet-based APIs, omit the id when creating new objects.

{
    "id": 23,
    "client": 1,
    "program_name": "Downtown Program",
    "physical_address_1": "123 Main St",
    "physical_address_2": "Suite 100",
    "physical_address_3": null,
    "physical_city": "San Diego",
    "physical_state": "CA",
    "physical_zip": "92101",
    "mailing_address_1": "PO Box 456",
    "mailing_address_2": null,
    "mailing_address_3": null,
    "mailing_city": "San Diego",
    "mailing_state": "CA",
    "mailing_zip": "92102",
    "primary_phone": "(619)555-1234",
    "primary_email": "contact@program.com",
    "billing_email": "billing@program.com",
    "client_instructions": "Special instructions for client",
    "invoice_instructions": "Net 30",
    "general_notes": "Additional notes",
    "is_active": true
}

/program-location-contact/: Program Location Contacts

This API manages the relationship between client contacts and program locations. Operations are supported via ModelViewSet APIs.

Note: This API does not support listing. To view program location contacts, use the programs field in the Client Contact API response.

Example Objects

{
    "id": 12,
    "program_location": 23,
    "client_contact": 1234,
    "title": "Director",
    "start_date": "2020-01-01",
    "end_date": "2023-07-01",
    "is_active": true,
    "is_program_contact": true
}

Field Descriptions

Field Type Description
id integer Unique identifier for the program location contact association
program_location integer ID of the program location
client_contact integer ID of the client contact
title string Job title for this contact at this program location
start_date date Start date of the contact's association with the program
end_date date End date of the contact's association with the program (nullable)
is_active boolean Whether this association is currently active
is_program_contact boolean Whether this contact is designated as a program contact

/item-price/: Item Prices

CRUD operations for item price objects supported via ModelViewSet APIs.

This API supports searching the list of item prices.

Search

The search functionality allows you to search by invoice item or item code using prefix matching.

Query Parameter Description
search Returns all item prices where the invoice item or item code starts with the search term

Example Objects

{
    "id": 1,
    "invoice_item": "Invoice Item",
    "item_code": "DS001",
    "default_price": "45.00",
    "default_tax_rate": "0.0775"
}

/program-location-item-price/: Program Location Item Prices

This API manages custom pricing for items at specific program locations. Operations are supported via ModelViewSet APIs.

Note: This API only supports listing and updating. Item prices are automatically created for program locations.

Filtering

When listing program location item prices with GET /program-location-item-price/, you can use the following query parameters to filter results:

Query Parameter Description
program_location_id Filter by program location ID
item_price_id Filter by item price ID

Filters can be combined. For example: GET /program-location-item-price/?program_location_id=23&item_price_id=1

Example Objects

{
    "id": 100,
    "item_price": {
        "id": 1,
        "invoice_item": "Drug Screen",
        "item_code": "DS001",
        "default_price": "45.00",
        "default_tax_rate": "0.0775"
    },
    "custom_price": "50.00",
    "custom_tax_rate": "0.08",
    "final_price": "50.00",
    "final_tax_rate": "0.08"
}

Field Descriptions

Field Type Description
id integer Unique identifier for the program location item price
item_price object The base item price object (read-only)
custom_price decimal Custom price override for this program location (nullable)
custom_tax_rate decimal Custom tax rate override for this program location (nullable)
final_price decimal The effective price (uses custom_price if set, otherwise default_price) (read-only)
final_tax_rate decimal The effective tax rate (uses custom_tax_rate if set, otherwise default_tax_rate) (read-only)