Stretch
Partner API/Reference

API reference.

42 endpoints across 10 resource groups — everything you need to run an incentive program on your existing Highnote card program. Base URL https://api.stretch.money/v1.

Start with authBack to Partner API
Base URL
https://api.stretch.money
Version
/v1
Auth
OAuth2 bearer (JWT)
Content type
application/json
Jump to

Authentication

2 endpoints

Clients authenticate with OAuth2 client credentials backed by an RSA key pair. Exchange the encoded secret for a short-lived bearer token, then call every resource endpoint with Authorization: Bearer <token>.

POST/v1/client-credentialsBasic (admin)

Issue a new client ID and secret. Returns the plain-text secret once, along with an RSA public/private key pair used to encrypt future auth requests.

Request & response+
Request
  • clientPasswordstringrequired

    Password that protects the returned client secret.

Response
  • clientIdstring
  • clientSecretstring

    Shown once. Store securely.

  • encodedClientSecretstring

    RSA-encrypted secret used on the token endpoint.

  • encodedPrivateKeystring
  • encodedPublicKeystring
  • creationTimestampnumber

    Milliseconds since epoch.

POST/v1/oauth2/tokenBasic (client)

Exchange credentials (or a refresh token) for an access token. Access tokens are valid for 1 hour; refresh tokens for 48 hours.

Request & response+
Request
  • grant_typestringrequired

    client_credentials or refresh_token (query param).

  • refresh-tokenheader

    Required when grant_type = refresh_token.

Response
  • accessTokenstring
  • refreshTokenstring
  • expiresInnumber

    Seconds until access token expires.

  • scopestring
  • tokenTypestring

    "bearer"

Programs

11 endpoints

A Program defines an incentive campaign — its award pool, participant cap, and the agreements participants must accept.

POST/v1/programs

Create a new program and fund its award pool.

Request & response+
Request
  • namestringrequired
  • programTypestringrequired

    "PAROLE" or "EDUCATION"

  • totalAwardPoolnumberrequired

    USD.

  • maxParticipantsnumberrequired
  • contactEmailstringrequired
  • contactPhonestringrequired
  • privacyAgreementIdstringrequired
  • userAgreementIdstringrequired
  • cardholderAgreementIdstring
  • financialAwardProgramTermsOfUseAgreementIdstring
Response
  • programIdstring
  • namestring
  • typestring
  • totalAwardPoolnumber
  • maxEligibleParticipantsnumber
  • createTimestampnumber
GET/v1/programs

List every program the authenticated client owns.

GET/v1/programs/{programId}

Retrieve a single program by ID.

PUT/v1/programs/{programId}

Update any subset of a program's fields.

DELETE/v1/programs/{programId}

Delete a program. Conflicts if participants are still enrolled.

GET/v1/programs/{programId}/statistics

Program totals: enrollment, awards paid, pending task value, completion percentages.

Request & response+
Response
  • totalEnrollmentnumber
  • totalAwardsPaidnumber
  • totalPendingTasksnumber
  • totalCompletedTasksnumber
  • enrollmentPercentagenumber
  • taskCompletionPercentagenumber
PUT/v1/programs/{programId}/users/{userId}/enroll

Enroll a user in the program.

DELETE/v1/programs/{programId}/users/{userId}/enroll

Unenroll a user from the program.

GET/v1/programs/{programId}/users

List every user enrolled in a program.

PUT/v1/programs/{programId}/tasks/{taskId}/assign

Attach a task to the program so all enrolled users can complete it.

DELETE/v1/programs/{programId}/tasks/{taskId}

Detach a task from a program.

Users

7 endpoints

Users are the real people who earn payouts. Create them with just enough identity to support card issuance.

POST/v1/users

Create a new user record.

Request & response+
Request
  • firstNamestringrequired
  • middleNamestringrequired
  • lastNamestringrequired
  • locationTypestringrequired

    e.g. "PRISON"

  • addressLineOnestring
  • citystring
  • statestring
  • zipstring
  • dateOfBirthstring
  • correctionalIdstring
  • internalIdstring

    Your own external identifier.

GET/v1/users

List every user the client has access to.

GET/v1/users/{userId}

Retrieve a single user.

PUT/v1/users/{userId}

Update a user's details.

GET/v1/users/{userId}/account-details

Get Highnote account identifiers (application, card, financial account) for a user.

PUT/v1/users/{userId}/webcredentials

Generate web credentials so the user can log into the cardholder app.

GET/v1/users/{userId}/usertasks

Fetch a user's task history with statuses and timestamps.

Tasks

7 endpoints

A Task is the rewardable action — completing training, checking in, paying rent on time. Every task has a monetary value paid out on completion.

POST/v1/tasks

Create a task with its reward amount.

Request & response+
Request
  • namestringrequired
  • monetaryValuenumberrequired

    USD, must be greater than 0.

GET/v1/tasks

List every task.

GET/v1/tasks/{taskId}

Retrieve a single task.

POST/v1/tasks/{taskId}/users/{userId}

Assign a task to a specific user. Reserves funds against the program award pool.

DELETE/v1/tasks/{taskId}/users/{userId}

Remove a task assignment from a user.

POST/v1/tasks/{taskId}/programs/{programId}/assign

Make a task available to every user in a program.

DELETE/v1/tasks/{taskId}/programs/{programId}

Detach a task from a program.

User tasks

2 endpoints

The lifecycle endpoints. Mark a task STARTED when work begins, COMPLETED to disburse the reward to the user's card.

PUT/v1/usertasks/{userTaskId}/start

Mark a task as started. Records startDate.

PUT/v1/usertasks/{userTaskId}/complete

Mark a task as completed. Stretch funds the user's card automatically and records finishDate.

Agreements

5 endpoints

Privacy policies, user agreements, cardholder agreements, and program terms-of-use. Create them once, attach to programs, capture user consent.

POST/v1/agreements

Create a new agreement version.

Request & response+
Request
  • agreementTypestringrequired

    PRIVACY_AGREEMENT | USER_AGREEMENT | CARDHOLDER_AGREEMENT | FINANCIAL_AWARD_PROGRAM_TERMS_OF_USE

  • agreementUrlstringrequired
GET/v1/agreements

List every agreement, all versions.

GET/v1/agreements/{agreementId}

Retrieve a single agreement.

GET/v1/agreements/latest

Return the latest version of each agreement type. Optional ?type= filter.

POST/v1/agreements/{agreementId}/users/{userId}

Capture a user's consent to an agreement. Returns a timestamped consent record.

Cards

5 endpoints

Card applications run KYC. Once approved, issue a card and check its delivery / activation / balance state.

POST/v1/applications

Submit a card application for a user.

Request & response+
Request
  • userIdstringrequired
  • cardTypestringrequired

    "NON_DESCRIPT" or "KYC"

Response
  • applicationIdstring
  • statestring
  • verificationStatusstring
GET/v1/applications/{applicationId}/status

Poll the state of a card application.

POST/v1/cards

Issue a card for an approved application.

Request & response+
Request
  • userIdstringrequired
Response
  • cardIdstring
  • activationStatusstring
  • pinStatusstring
  • deliveryStatusstring
  • orderWorkflowStatusstring
GET/v1/cards/{cardId}/status

Activation, PIN, delivery, and workflow state.

GET/v1/cards/{cardId}/balance

Current card balance in USD.

Client configuration

1 endpoint

Configure the card product and funding account used for every card issued under your client.

PUT/v1/configurations

Create or update your client-level card configuration.

Request & response+
Request
  • cardProductIdstringrequired
  • cardFundingAccountIdstringrequired
  • useProductFundingAccountbooleanrequired

Webhooks

1 endpoint

Register a webhook once to receive card-lifecycle and transfer events signed with an HMAC secret.

POST/v1/webhooks/webhook-configuration

Initialise your Highnote webhook subscriptions using the configured URL and signing secret.

Health

1 endpoint

A single liveness probe. No auth required.

GET/v1/healthcheckNone

Returns { status: "healthy!" } when the service is up.

Errors

Every non-2xx response follows a consistent shape. id is safe to log and share with support.

{
  "id": "2e6a7b2c-…",
  "httpCode": 409,
  "description": "Conflict",
  "detailDescription": "Program enrollment limit reached."
}
  • 400Invalid input or business-rule violation.
  • 401Missing or invalid bearer token.
  • 404Resource doesn’t exist or isn’t yours.
  • 409Conflict — e.g. enrollment limit, insufficient funds.

Ready to build?

Request sandbox keys and start a real integration in minutes.

Get API accessPartner API overview