Complete Prospects Order Workflow

This workflow demonstrates the full Prospects API integration journey for discovering and pre-qualifying look-alike businesses using Creditsafe data:

1. Authenticate - Obtain JWT token for API access
2. Preview Order - Estimate the number of matching companies before creating an order
3. Create Order - Submit a prospect order based on search criteria
4. Get Order Details - Retrieve the order status and results summary
5. Export Order - Download the order results in your preferred format (xls, xlsx, or csv)

Diagram summary: This workflow shows the complete Prospects order lifecycle. After authentication, the user previews an order to estimate matches, creates the order, polls for order completion, and exports the results. The export step may return 202 Accepted if still processing, requiring a retry.

Diagram summary: This sequence diagram shows the interaction between the client, Prospects API, and Creditsafe backend. Step 1 authenticates and returns a token. Step 2 previews the order with validation, showing success (200), validation errors (400), authentication errors (401), and credit errors (403). Step 3 creates the order, returning an orderId. Step 4 retrieves order details, showing success (200) and not found (404) paths. Step 5 exports results, showing ready (200), processing (202), and not found (404) responses.

All endpoints follow standard Prospects API error patterns. Errors include a correlationId for support tracking.

{
  "correlationId": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Validation failed",
  "details": "Invalid country code: 'XX' is not a supported country"
}

• 401 (Unauthorized): Re-authenticate once, then fail
• 403 (Forbidden): Do not retry (permission or credit issue)
• 404 (Not Found): Do not retry in workflow (indicates data flow error)
• 202 (Accepted): Retry Step 5 (export) with delays until 200 received
• 500/503 (Server Errors): Retry up to 3 times with exponential backoff

Authenticate with username and password to obtain a JWT token for API access.

Applies To: All workflows

POST /authenticate

{
  "username": "your-username",
  "password": "your-password"
}

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Preview the number of matching companies for prospect search criteria before creating an order. Returns a breakdown by country and registration type to help estimate scope and cost.

Applies To: Complete order workflow (optional but recommended)

POST /prospects/orders/preview

{
  "countries": ["GB", "US"],
  "industries": ["62", "70"],
  "employeeRange": {
    "min": 10,
    "max": 100
  }
}

{
  "totalCount": 1250,
  "breakdown": [
    {
      "country": "GB",
      "registrationType": "Limited",
      "count": 850
    },
    {
      "country": "US",
      "registrationType": "Corporation",
      "count": 400
    }
  ]
}

Create a new prospects order based on search criteria. This endpoint orders a list of companies matching specific criteria for prospecting and business development.

Applies To: Complete order workflow

POST /prospects/orders

{
  "countries": ["GB", "US"],
  "industries": ["62", "70"],
  "employeeRange": {
    "min": 10,
    "max": 100
  }
}

{
  "orderId": "a3f2b1d5-8c4e-4f2a-9e7b-1c5d6e8f9a0b",
  "status": "Processing",
  "createdDate": "2026-07-22T10:30:00Z"
}

Retrieve details of a specific prospect order by its unique identifier. Returns order status, progress information, search criteria used, and results summary when the order is completed.

Applies To: Complete order workflow

GET /prospects/orders/{id}

{
  "orderId": "a3f2b1d5-8c4e-4f2a-9e7b-1c5d6e8f9a0b",
  "status": "Completed",
  "createdDate": "2026-07-22T10:30:00Z",
  "completedDate": "2026-07-22T10:35:00Z",
  "totalResults": 1250,
  "searchCriteria": {
    "countries": ["GB", "US"],
    "industries": ["62", "70"]
  }
}

Export the results of a completed prospect order as a downloadable file. Supports xls, xlsx, and csv formats. If the export is still being processed, returns 202 Accepted and should be retried.

Applies To: Complete order workflow (after order is completed)

GET /prospects/orders/{id}/export?fileFormat={format}

Binary file stream (xls/xlsx/csv content)

{
  "message": "Export is still being processed. Please retry in a few moments.",
  "estimatedCompletionTime": "2026-07-22T10:40:00Z"
}

After creating an order (Step 3), poll Step 4 (Get Order Details) to check order status:

• Recommended interval: 5-10 seconds
• Maximum retries: 60 attempts (5-10 minutes total)
• Check: status field equals "Completed" before proceeding to Step 5

After requesting export (Step 5), if you receive 202 Accepted:

• Recommended interval: 5-10 seconds
• Maximum retries: 30 attempts (2.5-5 minutes total)
• Success: HTTP 200 with binary file stream

Choose the export format based on your downstream systems:

• CSV: Lightweight, universal compatibility, best for data import
• XLSX: Excel format with formatting support, best for manual review
• XLS: Legacy Excel format, use only for compatibility requirements