Version lives in the path. Every route on these pages starts /v1/, and that prefix is the one to build against.
Unversioned paths such as /verify, /jobs and /credits/balance still work for older integrations. They reach the same handlers, but new code should use /v1/ so a future version is a deliberate move on your side.
Adding a field to a response is not a breaking change, so parse defensively: a new key in a response object should not upset your client. Branch on status, and treat a reasonCode you do not recognize as extra detail.
Reference
| Change | Breaking? | What to do |
|---|---|---|
| New field in a response | No | Ignore what you do not read. |
| New optional request field | No | Nothing. Your existing calls keep working. |
| New reason code inside a status | No, by our definition | Handle the default case and branch on status. |
| Field removed or renamed | Yes | Would ship under a new version prefix. |
A client that still works next year
Two small habits decide whether an additive change breaks you. The first is your JSON parser. Some typed languages ship parsers that fail on any field they weren't told about. A client built that way breaks on the day we add one. Set yours to ignore unknown fields.
Your switch statements are the second. Say a release adds a reasonCode value your code has never seen. If you switch on reasonCode with no default branch, that row falls through or throws. Branch on status, keep a default in every switch you write, and treat a strange reasonCode as plain text for your logs and nothing more.
Give status a default branch too, even though the four statuses are settled. The safest default is to treat a verdict you don't know the way you treat unknown. Keep the contact, hold it out of the main send, and tell a person so they can update the client.
Keeping the reason codes in one place
The reasonCode list is documented on the result codes page, and it can still grow. Put every read of it inside one small module in your client, so a new value is a one-line change. Reading it in six files means six edits when a code is added.
Don't store the list in a database enum type, since a new value would then need a migration before your code could save the row. Store the string you received.
For the settled fields, relax. status, smtpCode, checkedAt and the job counts are the core of the contract. A rename there would ship under a new version prefix.
Questions developers ask
Should I use the unversioned paths?
Use /v1/. The unversioned paths exist so older integrations keep working, and they are not the ones to start new code on.
Will /v1/ break?
New fields and new reason codes will appear, which is why a client should ignore what it does not recognize.
Is there a changelog?
These pages are the reference for the API as it stands. Contact support with the request id of any response that surprises you.