This page describes public APIs available to our customers to manage financial data such as bill payers, invoices, and payments. All data given in this document is example data and should not be used with the production APIs.
Bill payers, invoices, and payments are uniquely identified by UUIDs. When Famly creates a bill payer, invoice, or payment, we will generate a UUID and include it in the data returned by the API call. Institutions will need to store these IDs and use them when updating or deleting these entities. All UUIDs and data given in this document are presented as examples only.
Bill payers are assigned to a specific institution or setting. You must provide a siteId when creating a bill payer. You can retrieve a list of site IDs for an organization using an API documented here.
Some queries in the API use pagination to limit the number of results returned in a single request. Generally, pagination APIs return an object called results and a cursor called next. If next is not null, then there is at least one more page of results left; pass the most recent value for next back to the API to fetch the next page.
A bill payer represents an entity responsible for paying some fraction of the bills for one or more children. A child may have multiple bill payers who share bills and a bill payer may be associated with more than one child. For any child that has associated bill payers, we require that the total shares of all bill payers add up to 1.0 at all times. This means that when creating a bill payer, it is an error to provide a multiplier of any value other than 1.0 if the child has no other bill payers. If no multiplier is provided, each new bill payer for a child will be assigned an equal portion of the child’s bill.
Moreover, a bill payer may represent multiple invoice recipients. For example, if the bill payer represents a family with two parents, each parent may be an invoice recipient and a copy of each invoice will be sent to both parents. Between them, they are responsible for paying the invoice total.
A child ID is required to associate a bill payer with a child. There is an API for retrieving a list of children for a list of sites, documented here.
The only field require to create a new bill payer is the name. To create a new bill payer, use the following mutation:
mutation CreateBillPayer($billPayers: [BillPayerInput!]!) {
billPayers {
create(billPayers: $billPayers) {
billPayerId
siteId
name
address {
street
zip
city
}
email
phone
accountNumber
sortCode
note
children {
childId
share {
multiplier
}
}
invoiceRecipients {
relationId
name
email
}
}
}
}
Here is an example of the JSON data to provide with this query:
{
"billPayers": [
{
"siteId": "53bf55a3-7f1d-487b-adcc-9daf133025bc",
"name": "William Payer III",
"phone": "+44 07911 123456",
"address": {
"street": "123 Famly Horizons Ln",
"zip": "WR1",
"city": "Worcester"
},
"email": "[email protected]",
"accountNumber": "12345",
"sortCode": "4444",
"note": "Notable",
"children": [
{
"childId": "13226507-5300-46a0-aa91-7244c99a1f52",
"share": {
"multiplier": 0.3333333333333333
}
},
{
"childId": "1a31eb29-7a1f-4b7b-8343-b2b8f9f7624b",
"share": {
"multiplier": 0.5
}
}
],
"invoiceRecipients": [
{
"relationId": "b2bf5a7a-2eea-4ce0-a51c-549169b1557f"
},
{
"childId": "1a31eb29-7a1f-4b7b-8343-b2b8f9f7624b",
"name": "William Shakespayer",
"email": "[email protected]"
}
]
}
]
}