The January API is a set of programmatic endpoints that can be used to interact with January data. This API is documented in OpenAPI format.

January will generate an API token to use with all of your requests. You can attach the token in the header with the following key value:

Authorization: Bearer <API_TOKEN >

All API requests have a rate limit of 100 / minute. Please contact us if this is insufficient for your needs.

Endpoints that use pagination will accept page and limit arguments as query parameters. A max of 1000 results per page will be returned. page will default to 1 unless a value is given and limit will default to 1000.

When reading paginated responses from the API, the follow response headers will be sent:

• X-Page: The current page
• X-Per-Page: The current limit
• X-Total-Count: The total number of pages available

All dates should be in ISO8601 format, e.g. '2020-08-13'.

All currency fields should be provided as integers representing the number of cents. In other words, the dollar amount $1.99 should be sent as 199, not as 1.99 or as "$1.99".

Every response will contain a X-January-API-Request-ID value, unique to a response.

Success response structure

Successful responses are indicated with a 200-series HTTP code and a JSON-based payload. The data field in JSON responses will contain the specific objects associated with the leveraged resource.

Error response structure

Error responses are indicated with a non-200-series HTTP code and sometimes a JSON-based payload. We cannot guarantee that all error responses will contain the same response format or a consistent repsonse format, we recommend that the HTTP code's core meaning to take precedence.

In general, January will only make backwards-compatible changes to our APIs. For example, we might:

• Make new properties available on JSON objects
• Allow new parameters as inputs
• Make changes specified as valid by this documentation, even if the behavior is new (for example, we might begin returning null for a property even if we never returned null for that property before as long as we documented the field as nullable)

If we need to make a breaking change, we will introduce a new API endpoint. For example, the following would be breaking changes:

• Changing the shape of JSON responses other than adding new properties
• Adding a new value to an enum, or changing the semantics of an existing value
• Imposing additional requirements on API inputs

There are exceptions to this stability promise. Specifically, new APIs will be marked "Beta" for a while, and are not subject to this policy. This is to allow us to quickly iterate on APIs so they can better serve clients' needs. Clients making use of APIs marked "Beta" should expect to work directly with us to adjust to changes we make to the API as it evolves.

We will announce API deprecations in advance and provide a timeline for transitioning to replacements.

Webhooks allow you to opt into receiving real-time events about the accounts you've placed with January. These events are sent via HTTPS to your backend system. Some examples of real-time events include being alerted when a borrower has made a payment, or when an account has been fully paid off.

Note: Webhook events are only available for pre-chargeoff accounts.

To validate that a webhook was sent by January, every incoming request is signed with a signature stored under the HTTP Header x-signature.

Signature

To extract the signature, please hash the request body using HMAC SHA-256, with your webhook key as the shared secret (see "Retrieving Your Webhook Key" below).

Validating the Signature

The signature you generate above should be equivalent to the signature we pass through the HTTP Header x-signature. If not, the request may be from another source.

• Contact api@january.com to request your private webhook key - please do NOT share this key outside your organization.
• If your webhook key is accidentally exposed to the public, please contact api@january.com to rotate your key.

To subscribe to a webhook, please contact api@january.com outlining:

• Webhook Name: which webhook you want to subscribe to (e.g. payment_plan_created). See "Webhook Events" section below for a list of webhooks.
• Webhook URL: the endpoint URL you want the webhook request to be sent to (e.g. https://www.client-name.com/events/payment-plan/create).
  • We will be making HTTP POST requests to this endpoint. To see a detailed request body schema, refer to the Webhooks documentation section below.

• We will retry each webhook event up to 10 times if we receive a non 2XX response from your webhook subscription URL.
• Please respond to the request with a 200 to confirm successful receipt of the request.

The below is a list of all the webhook events you can subscribe to, followed by a description of what information will be shared:

1. payment_plan_created - A payment plan was created for an account.
2. payment_plan_updated - A payment plan was updated for an account.
3. payment_plan_deleted - A payment plan was deleted for an account.
4. payment_received - A payment was successfully received and applied to an account.
5. payment_returned - A payment was returned (i.e. refunded or charged back).
6. email_sent - January (as the client) sent an email to a borrower.
7. email_received - January (as the client) received an email from a borrower.
8. inbound_phone - January (as the client) received an incoming phone call from a borrower.
9. outbound_phone - January (as the client) made an outgoing phone call to a borrower.
10. account_status_update - A borrower's account status has changed, e.g. from placed to resolved.

This below snippet is an example handler for webhook events (in Python).

def _is_valid_january_signature():
    def wrapper(event_handler):
        def wrapped_event_handler(*args):
            webhook_signature = request.headers["x-signature"]
            body = request.get_data()
            secret_key = <your webhook key (ideally retrieved from some kind of secure secret storage)>
            derived_signature = hmac.new(
                bytes(
                    secret_key,
                    "utf-8",
                ),
                body,
                hashlib.sha256,
            ).hexdigest()
            if hmac.compare_digest(
                bytes(derived_signature, "utf-8"), bytes(webhook_signature, "utf-8")
            ):
                return event_handler(*args)
            else:
                abort(403, "Invalid Signature")

        wrapped_event_handler.__name__ = event_handler.__name__
        return wrapped_event_handler

    return wrapper


@api.route("/january_events/transactions", methods=("POST",))
@_is_valid_january_signature()
def handle_webhook():
    logger.info(
        "Webhook received",
        {"json": request.json, "headers": request.headers},
    )
    return jsonify({"foo": "bar"}), 200

For support and feedback please email api@january.com, we'd love to hear from you.

Connection and health status of January API

Retrieve and update debts

Access debtor transactions

Create debts

Recall debts

Track communications between January and borrowers

Monitor payment plan creation, update, or deletion

Monitor payments made by borrowers

Monitor the status of accounts. Possible statuses include:

• placed: January is working to collect on this account.
• ceased: January is no longer working to collect on this account. Possible reasons include:
  • Bankruptcy Notice
  • Deceased Notice
• canceled: January is no longer working to collect on this account because it was recalled by the client.
• resolved: January is no longer working to collect on this account because it has been paid in full.
• charged-off: January is no longer working to collect on this account because it is charged-off.