Skip to main content

​
Summary

We are tightening the required-field contract on POST /customers and POST /customers/batch so that every customer we board arrives with the data needed to contact them lawfully and verify their identity. Two redundant fields are being removed at the same time. Nothing on this page is enforced yet. Requests that are valid today remain valid until further notice. We will give partners ample time to adjust before introducing any breaking changes — you will be notified well in advance so you can migrate on your own schedule rather than in response to a failure. Endpoints affected:
  • POST /customers
  • POST /customers/batch (same per-customer payload)
Endpoints not affected: POST /customers/schedule/sync, PUT /customers/{id}, and every loan, call, text, and payment endpoint.

​
What is changing

id, taskType, streetAddress1, and city are unchanged. streetAddress2, doNotCall, externalMetadata, and loanIds remain optional.

​
Why each change

At least one of email or phoneNumber. Every customer needs at least one channel we can reach them on — a record with neither cannot be worked. Today phoneNumber is unconditionally required, which turns away email-only accounts. Relaxing that while requiring one of the pair is both stricter in effect and more flexible in practice. At least one of timezone or zipCode. We may only place calls during hours permitted by the borrower’s local time, so TCPA compliance depends on knowing where they are. Supplying either is sufficient: when timezone is omitted we derive it from zipCode. If the ZIP cannot be resolved to a timezone, the request is rejected with 400 rather than silently defaulting — a wrong timezone means calls placed outside legal hours. state always required. State determines which lending and collections rules apply to the account, and several states are restricted per-portfolio. We need it regardless of how the rest of the record was populated. birthday and ssnLastFour required. Both are used to verify a borrower’s identity before discussing account details on a call. Without them, an agent cannot complete verification and the conversation cannot proceed. test → isTest. The API already returns isTest on every customer response, but accepts test on the way in. Aligning the write field to the read field removes a needless asymmetry. loanId removed. On POST /customers this field is accepted and then ignored — it has never had any effect. loanIds is the field that actually controls which loans are imported, so a single loan ID belongs there as a one-element array.

​
Migrating your payload

A request that is valid today:
The same request under the new contract — birthday and ssnLastFour added, test renamed to isTest, loanId moved into loanIds:
Note that loanIds is an array of integers, not strings. Because email/phoneNumber and timezone/zipCode are at-least-one pairs, a minimal payload only needs one of each:

​
What you can do now vs. what to wait for

Read this section carefully if you plan to migrate early — some of the new fields are not yet wired up. Safe to do now:
  • Start sending birthday, ssnLastFour, and state on every request. All three are already accepted and stored today; they are simply not yet enforced.
  • Move a single loanId value into loanIds. loanIds is already honored; loanId is already ignored on this endpoint, so there is no behavior to lose.
Do not do yet:
  • Do not switch test to isTest until we confirm the change is live. isTest is not accepted on the request today and unknown fields are ignored, so a payload sending isTest: true would silently create a non-test customer. Keep sending test until you are notified.
Only after the change takes effect:
  • Dropping phoneNumber (relying on email alone) or dropping timezone (relying on zipCode alone). Both are unconditionally required today and omitting either returns a 400 until the new contract takes effect.

​
Error behavior

Missing required fields return 400 Bad Request with the offending fields named, in the same shape used today:
For the at-least-one pairs, the message names the pair rather than a single field. A zipCode that cannot be resolved to a timezone also returns 400.

​
Questions

If any of these fields are not available in your system, or you need more time to adjust, contact your Finosu account manager so we can plan around it.