API Reference
  1. 365 Finance API

Authentication

The new 365 Finance API uses API Key authentication for secure and simple access to your data. Each partner receives a unique API key that automatically filters results to show only data relevant to your organization.


🔑 How to Authenticate

Step 1: Obtain Your API Key

Contact your account manager at [email protected] to request an API key. You will receive:

  • A unique API key (64-character hexadecimal string)
  • Access to the staging environment for testing
  • Documentation and integration support

Step 2: Include API Key in Request Headers

Add the X-API-Key header to every API request:

GET /cashadvances?startDate=2025-11-01&endDate=2025-12-01 HTTP/1.1
Host: staging-api.365finance.co.uk
X-API-Key: your-api-key-here

Important: The API key must be included in the X-API-Key header (case-sensitive) for all requests.

💻 Code Examples

cURL

curl -X GET "https://staging-api.365finance.co.uk/cashadvances?startDate=2025-11-01&endDate=2025-12-01" \
  -H "X-API-Key: your-api-key-here"

JavaScript / Node.js

const response = await fetch(
  'https://staging-api.365finance.co.uk/cashadvances?startDate=2025-11-01&endDate=2025-12-01',
  {
    headers: {
      'X-API-Key': 'your-api-key-here'
    }
  }
);

const data = await response.json();
console.log(data);

Python

import requests

headers = {
    'X-API-Key': 'your-api-key-here'
}

params = {
    'startDate': '2025-11-01',
    'endDate': '2025-12-01'
}

response = requests.get(
    'https://staging-api.365finance.co.uk/cashadvances',
    headers=headers,
    params=params
)

data = response.json()
print(data)

PHP

<?php
$apiKey = 'your-api-key-here';
$url = 'https://staging-api.365finance.co.uk/cashadvances?startDate=2025-11-01&endDate=2025-12-01';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'X-API-Key: ' . $apiKey
));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$data = json_decode($response, true);

curl_close($ch);
print_r($data);
?>

C# / .NET

using System;
using System.Net.Http;
using System.Threading.Tasks;

var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "your-api-key-here");

var response = await client.GetAsync(
    "https://staging-api.365finance.co.uk/cashadvances?startDate=2025-11-01&endDate=2025-12-01"
);

var data = await response.Content.ReadAsStringAsync();
Console.WriteLine(data);

Java

import java.net.http.*;
import java.net.URI;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://staging-api.365finance.co.uk/cashadvances?startDate=2025-11-01&endDate=2025-12-01"))
    .header("X-API-Key", "your-api-key-here")
    .GET()
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

🔒 Security Best Practices

Keep Your API Key Secure

  • Never commit to version control - Add your API key to .gitignore or use environment variables
  • Don't expose in client-side code - API keys should only be used in server-side applications
  • Use environment variables - Store your API key in environment variables, not hardcoded in your application

Example (.env file):

API_KEY=your-api-key-here
API_URL=https://staging-api.365finance.co.uk

Rotate Keys Regularly

Request new API keys periodically for enhanced security. Contact [email protected] to rotate your keys.

Use HTTPS Only

All API requests must use HTTPS. HTTP requests will be rejected. This is enforced by the API Gateway.

Monitor Usage

Track your API usage and report any suspicious activity to [email protected] immediately.

IP Whitelisting (Optional)

For additional security, you can whitelist specific IP addresses. Contact [email protected] to configure IP restrictions for your API key.

Benefits:

  • Only requests from whitelisted IPs will be accepted
  • Additional layer of security beyond API key
  • Ideal for production environments with static IPs

⚠️ Authentication Errors

401 Unauthorized - Missing API Key

Cause: The X-API-Key header is missing from your request.

Response:

{
  "error": {
    "code": "MISSING_API_KEY",
    "message": "Authentication required",
    "details": "API key is required. Please include X-API-Key header in your request.",
    "requestId": "req-abc-123",
    "timestamp": "2026-01-28T14:55:00.000Z"
  }
}

Solution:

  • Ensure you're including the X-API-Key header in your request
  • Check for typos in the header name (it's case-sensitive)
  • Verify your HTTP client is sending headers correctly

403 Forbidden - Invalid API Key

Cause: The API key provided is invalid, expired, or has been deactivated.

Response:

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Access denied",
    "details": "The provided API key is invalid or has been deactivated. Please contact support.",
    "requestId": "req-abc-124",
    "timestamp": "2026-01-28T14:55:00.000Z"
  }
}

Solution:

  • Verify you're using the correct API key
  • Check if your API key has been deactivated
  • Contact [email protected] to verify your API key status or request a new one

🧪 Testing Your Authentication

Staging Environment

Test your API key in the staging environment before going live:

curl -X GET "https://staging-api.365finance.co.uk/cashadvances?startDate=2025-11-01&endDate=2025-12-01" \
  -H "X-API-Key: your-staging-api-key"

Expected Success Response (200 OK)

{
  "RequestId": "req-abc-123",
  "TotalRecords": 5,
  "Timestamp": "2026-01-28T14:55:00.000Z",
  "CashAdvances": [
    {
      "FundedDate": "2025-11-20",
      "FundedAmount": 15000.00,
      "CustomerReference": "CUST-001",
      "CashAdvanceNumber": "CA-2025-001",
      "BrokerReference": "BRK-001",
      "FactorRate": 1.15,
      "TotalRepayment": 17250.00
    }
  ]
}

Verify Authentication is Working

Test 1: Valid API Key

# Should return 200 OK with data
curl -i -X GET "https://staging-api.365finance.co.uk/cashadvances?startDate=2025-11-01&endDate=2025-12-01" \
  -H "X-API-Key: your-valid-api-key"

Test 2: Missing API Key

# Should return 401 Unauthorized
curl -i -X GET "https://staging-api.365finance.co.uk/cashadvances?startDate=2025-11-01&endDate=2025-12-01"

Test 3: Invalid API Key

# Should return 403 Forbidden
curl -i -X GET "https://staging-api.365finance.co.uk/cashadvances?startDate=2025-11-01&endDate=2025-12-01" \
  -H "X-API-Key: invalid-key-12345"

🌐 Environments

Staging

URL: https://staging-api.365finance.co.uk

Purpose:

  • Testing and development
  • Safe environment for integration testing
  • Uses Salesforce sandbox data
  • No impact on production data

Use staging for:

  • Initial API integration
  • Testing error handling
  • Validating request/response formats
  • Performance testing

Production

URL: https://api.365finance.co.uk

Purpose:

  • Live production data
  • Real customer transactions
  • Production Salesforce instance

Requirements:

  • Separate production API key
  • Completed staging testing
  • Approved by your account manager

📊 Data Filtering

Your API key is automatically linked to your partner/broker ID. All API responses are automatically filtered to show only data relevant to your organization.

What this means:

  • You only see cash advances for your brokerage
  • No need to specify partner ID in requests
  • Data isolation is enforced at the API level
  • Secure multi-tenant architecture

Example:
If your partner ID is BRK-001, all API calls will only return cash advances where you are the broker, regardless of query parameters.

🔄 API Key Lifecycle

Requesting a New API Key

  1. Contact [email protected]
  2. Provide your company name and contact information
  3. Receive your API key via secure channel

Rotating API Keys

When to rotate:

  • Suspected key compromise
  • Employee departure
  • Regular security maintenance (recommended quarterly)
  • Moving from staging to production

How to rotate:

  1. Request new API key from [email protected]
  2. Update your application with new key
  3. Test with new key in staging
  4. Deploy to production
  5. Notify support to deactivate old key

Tip: Request the new key before deactivating the old one to avoid downtime.

Deactivating API Keys

Contact [email protected] to deactivate:

  • Compromised keys
  • Unused keys
  • Keys for terminated integrations

Deactivated keys will immediately return 403 Forbidden errors.

📞 Support & Troubleshooting

Common Issues

Issue: "I'm getting 401 errors even with a valid API key"

Solutions:

  • Verify header name is exactly X-API-Key (case-sensitive)
  • Check for extra spaces in the API key value
  • Ensure you're not accidentally encoding the header
  • Test with cURL first to isolate application issues

Issue: "API key works in staging but not production"

Solutions:

  • Verify you're using the production API key (not staging key)
  • Confirm production key has been activated
  • Check if IP whitelisting is enabled for production

Issue: "Getting 403 errors after IP change"

Solutions:

  • Your IP address may have changed (dynamic IP)
  • Contact support to update IP whitelist
  • Consider using a static IP or VPN for production

Request ID for Support

Every API response includes a RequestId field. Always include this when contacting support:

{
  "RequestId": "req-abc-123",
  ...
}

This helps our support team quickly locate your request in our logs.

Contact Support

Email: [email protected]

Include in your support request:

  • Your company name
  • API key (last 8 characters only)
  • RequestId from error response
  • Timestamp of the issue
  • Full error message
  • Steps to reproduce

✅ Quick Start Checklist

  • Request API key from [email protected]
  • Receive API key and staging access
  • Test authentication with cURL
  • Integrate API key into your application
  • Store API key securely (environment variables)
  • Test in staging environment
  • Verify data filtering is working correctly
  • Handle authentication errors (401, 403)
  • Request production API key when ready
  • Configure IP whitelisting (optional)
  • Deploy to production
  • Monitor API usage and errors

Last Updated: January 28, 2026
API Version: 2.0.0
Support: [email protected]

Updated 5 months ago

Did this page help you?

Updated 5 months ago

Did this page help you?