Communications Pausing Guide

Overview

When loan applications are created through the Public API, borrower communications (welcome emails, stipulation notifications, etc.) are paused by default. This allows partners to:

• Control the timing of borrower outreach
• Coordinate communications with their own workflows
• Prevent premature contact before the borrower has committed to an offer

Communications remain paused until the partner explicitly signals that the borrower has selected an offer by calling the Accept Offer endpoint.

Note: This feature only applies to applications created via the Public API. Applications created through the Thrive UI send communications immediately as normal.

How It Works

Communication Flow

Public API Application Created
         │
         ▼
    ┌─────────────────────────────────────┐
    │  Communications PAUSED              │
    │  - Welcome email NOT sent           │
    │  - Stipulation emails NOT sent      │
    │  - Application sits in Hard Pull    │
    │    Auth or Pend Clearance           │
    └─────────────────────────────────────┘
         │
         │  Partner calls PUT /v2/application/accept-offer
         ▼
    ┌─────────────────────────────────────┐
    │  Communications ENABLED             │
    │  - Welcome email sent immediately   │
    │  - Stipulation emails sent normally │
    │  - All future comms proceed         │
    └─────────────────────────────────────┘

Application States Affected

Communications are paused when the application is in:

Accept Offer Endpoint

Endpoint Details

Authentication

Request Body

Request Example

curl -X PUT https://api.partnerwiththrive.com/public/v2/application/accept-offer \
  -H "Content-Type: application/json" \
  -H "x-thrive-client-id: your_client_id" \
  -H "x-thrive-client-secret: your_client_secret" \
  -d '{
    "thrive_application_uid": "c4ff1199-a135-4739-b110-91f7c1bf9d2f",
    "selected_product_uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }'

Request with Linked Applications

If the borrower had multiple competing applications and selected one offer, you can close the others:

curl -X PUT https://api.partnerwiththrive.com/public/v2/application/accept-offer \
  -H "Content-Type: application/json" \
  -H "x-thrive-client-id: your_client_id" \
  -H "x-thrive-client-secret: your_client_secret" \
  -d '{
    "thrive_application_uid": "c4ff1199-a135-4739-b110-91f7c1bf9d2f",
    "selected_product_uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "linked_application_uids": [
      "d5e6f7a8-b9c0-1234-5678-90abcdef1234",
      "f8a9b0c1-d2e3-4567-890a-bcdef1234567"
    ]
  }'

Successful Response

{
  "timestamp": "2025-01-12T10:30:00.000Z",
  "statusCode": 200,
  "result": {
    "data": {
      "thrive_application_uid": "c4ff1199-a135-4739-b110-91f7c1bf9d2f",
      "offer_selected": true
    },
    "error": null
  }
}

What Happens When Accept Offer is Called

When you call the accept-offer endpoint, the following actions occur:

1. Application Variables Updated

   • offer_selected is set to true
   • selected_product is set to the product code

2. Welcome Email Sent

   • The borrower receives the welcome email that was initially suppressed

3. Communications Enabled

   • All future stipulation/task emails will be sent normally
   • The application proceeds through the standard workflow

4. Linked Applications Closed (if provided)

   • Any application UIDs in linked_application_uids are moved to Closed status

Error Handling

Product Not Found

{
  "timestamp": "2025-01-12T10:30:00.000Z",
  "statusCode": 400,
  "result": {
    "data": null,
    "error": {
      "message": "Could not find the specified product. Please check the id submitted and try again"
    }
  }
}

Solution: Verify the selected_product_uid is a valid product UID from your available products.

Application Not Found

{
  "timestamp": "2025-01-12T10:30:00.000Z",
  "statusCode": 400,
  "result": {
    "data": null,
    "error": {
      "message": "Could not find the specified application. Please check the id submitted and try again"
    }
  }
}

Solution: Verify the thrive_application_uid matches an existing application.

Validation Errors

{
  "timestamp": "2025-01-12T10:30:00.000Z",
  "statusCode": 400,
  "result": {
    "data": null,
    "error": {
      "message": "\"thrive_application_uid\" is required"
    }
  }
}

Solution: Ensure all required fields are provided in the request body.

Common Workflows

Workflow 1: Standard Offer Acceptance

Use Case: Borrower reviews offer with partner's rep and decides to proceed.

// After borrower confirms they want to proceed with Thrive financing
const acceptOffer = async (applicationUid, productUid) => {
  const response = await fetch('/public/v2/application/accept-offer', {
    method: 'PUT',
    headers: {
      'Content-Type': 'application/json',
      'x-thrive-client-id': process.env.THRIVE_CLIENT_ID,
      'x-thrive-client-secret': process.env.THRIVE_CLIENT_SECRET
    },
    body: JSON.stringify({
      thrive_application_uid: applicationUid,
      selected_product_uid: productUid
    })
  });

  const result = await response.json();

  if (result.result.error) {
    throw new Error(result.result.error.message);
  }

  // Borrower will now receive welcome email and any pending stip notifications
  return result.result.data;
};

Workflow 2: Multiple Offers with Selection

Use Case: Borrower was presented multiple financing options and selected one.

// Borrower selects one offer, close the others
const selectOffer = async (selectedAppUid, productUid, rejectedAppUids) => {
  const response = await fetch('/public/v2/application/accept-offer', {
    method: 'PUT',
    headers: {
      'Content-Type': 'application/json',
      'x-thrive-client-id': process.env.THRIVE_CLIENT_ID,
      'x-thrive-client-secret': process.env.THRIVE_CLIENT_SECRET
    },
    body: JSON.stringify({
      thrive_application_uid: selectedAppUid,
      selected_product_uid: productUid,
      linked_application_uids: rejectedAppUids  // These will be closed
    })
  });

  return response.json();
};

// Example usage
await selectOffer(
  'selected-app-uid',
  'product-uid',
  ['rejected-app-1', 'rejected-app-2']
);

Workflow 3: Delayed Acceptance

Use Case: Application created but borrower needs time to decide.

// Application created via Public API - communications are paused
const app = await createApplication(borrowerData);

// Days/weeks later, borrower decides to proceed
// Partner's system triggers accept-offer when borrower confirms
const onBorrowerConfirmation = async (applicationUid) => {
  // Get the product from the original application
  const appDetails = await getApplication(applicationUid);

  await acceptOffer(applicationUid, appDetails.product_uid);

  // Now: Welcome email sent, stip emails will flow, borrower is engaged
};

Integration Checklist

When implementing communications pausing:

• Store thrive_application_uid when creating applications
• Store product_uid for use when accepting offers
• Implement UI/workflow for borrower to confirm offer selection
• Call accept-offer endpoint when borrower confirms
• Handle error responses appropriately
• (Optional) Track linked applications for multi-offer scenarios

Best Practices

1. Call accept-offer promptly - Once a borrower decides to proceed, call the endpoint so they receive timely communications.

2. Don't call multiple times - The endpoint is idempotent, but calling it repeatedly is unnecessary.

3. Store application UIDs - Keep track of application UIDs returned from creation to use when accepting offers.

4. Handle linked applications - If you create multiple applications for comparison, use linked_application_uids to clean up rejected options.

5. Monitor for errors - Log and alert on accept-offer failures to ensure borrowers receive their communications.

Testing

Sandbox Environment

Test the accept-offer endpoint in the development environment:

# Development base URL
https://dev.partnerwiththrive.com/public/v2/application/accept-offer

Test Scenarios

1. Basic acceptance - Create application, call accept-offer, verify welcome email sent
2. With linked applications - Create multiple applications, accept one with linked UIDs, verify others closed
3. Invalid product - Call with non-existent product UID, verify error response
4. Invalid application - Call with non-existent application UID, verify error response

Need Help? Contact your Thrive integration manager for assistance with communications pausing implementation.