Getting Started with SIPS API

This guide walks you through the first 4 steps of integration: getting credentials, authenticating, validating customers, and exploring branch locations.

🎯 What You'll Accomplish

By the end of this guide, you will:

✅ Obtain API credentials from SRS

✅ Authenticate and get your access token

✅ Validate a customer to ensure they have access

✅ Explore branch locations and understand available data

✅ Be ready to proceed to the Place Order Guide

⏱️ Time to Complete: 30-45 minutes

📋 Integration Progress Tracker - Track Your Progress

Prerequisites (Authentication Guide - Steps 1-4):

API credentials obtained
Access token retrieved
Customer validated
Branch locations explored

Steps 5-8 Progress (Next: Order Flow Guide):

🏪 Step 5: Customer branches retrieved
📦 Step 6: Products browsed at branch
💰 Step 7: Real-time pricing obtained
✅ Step 8: Order successfully submitted

Key Data Collected:

jobAccountNumber saved (from Step 5)
Product IDs identified (from Step 6)
Pricing validated (from Step 7)
Order ID received (from Step 8)

Integration Complete:

First test order submitted successfully
Order confirmation received
Webhook setup planned (for Production)
Error handling implemented

🔄 How Steps 1-4 Work Together

Step 1: Request API Credentials

📧 How to Request Credentials - Click to expand

Email Template

Email APISupportTeam@srsdistribution.com

What to Include:

✅ Your company name

✅ Integration use case (brief description)

✅ Technical contact (name and email)

✅ Environment needed (QA for testing, Production for live orders)

✅ Phone number (optional but helpful)

Response Time:

📅 Typically 1-2 business days

🚨 Urgent requests may be expedited (mention in subject)

What You'll Receive

You will receive:

Credential	Description	Example
`client_id`	Your unique application identifier	`srs_partner_12345`
`client_secret`	Confidential key (keep secure!)	`a1b2c3d4e5f6g7h8...`
API Base URL	Environment endpoint	`https://services-qa.roofhub.pro`
Environment	Testing environment type	`Staging`

Staging Environment: You will be set up for synchronous order submission only for testing. Asynchronous order submission with webhooks is available in Production and is recommended for live deployments.

IMPORTANT: Do NOT share your credentials with customers or commit them to version control.

Pro Tip: Use a secure secrets management system (Azure Key Vault, AWS Secrets Manager, HashiCorp Vault, etc.) to store credentials. Environment variables should only be used as a mechanism to retrieve credentials from the secrets manager at runtime—never store sensitive values directly in environment variables.

🔒 Security Best Practices for Credentials - Click to expand

DO ✅:

Store credentials in a secrets management system and retrieve them at runtime:

Use secrets management systems:

AWS Secrets Manager

Azure Key Vault

HashiCorp Vault

Kubernetes Secrets

Rotate credentials every 90 days

SRS will enforce credentials rotation every 6 months

Use different credentials for Staging vs Production

Limit access to credentials (need-to-know basis)

Audit credential usage regularly

DON'T ❌:

Commit to Git/version control

Share via email or chat

Hard-code in source files

Store in plain text files

Share with customers or end-users

Use same credentials across environments

Log credentials in application logs

Compromised Credentials?

Contact SRS API Support Team immediately

Request credential rotation

Review access logs for unauthorized usage

Update all systems with new credentials

Step 2: Authenticate & Get Access Token

🔑 Understanding OAuth 2.0 Authentication - Click to expand

What is OAuth 2.0 Client Credentials?

OAuth 2.0 is an industry-standard protocol for authorization. The Client Credentials flow is designed for server-to-server authentication.

How it works:

Key Benefits:

✅ Secure: No user passwords involved

✅ Stateless: Tokens are self-contained

✅ Scalable: Works across distributed systems

✅ Time-limited: Tokens expire (reduces risk)

✅ Industry standard: OAuth 2.0 is widely supported

Token Lifecycle:

Request Token

🔑 Request token with your client credentials

Token Valid Period

⏰ Token remains valid for 24 hours (86,400 seconds)

Refresh Before Expiry

🔄 Implement automatic refresh before token expires

Handle Expiration

🚫 Expired tokens are rejected with 401 Unauthorized error

Authentication Process

SIPS uses OAuth 2.0 Client Credentials flow:

Send Credentials

Send your client_id and client_secret to POST /authentication/token

Receive Access Token

Receive an access_token valid for 24 hours

Use Token in API Calls

Include token in Authorization: Bearer {token} header for all API requests

Make Your First Authentication Request

Endpoint: POST /authentication/token

📤 Request Details - Click to expand

Request Headers:

Content-Type: application/json

Request Body:

{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "grant_type": "client_credentials",
  "scope": "ALL"
}

✅ Successful Response - Click to expand

{
  "token_type": "Bearer",  // 🔑 Always "Bearer" for OAuth 2.0
  "expires_in": 86400,  // ⏰ Token expires in 24 hours (86400 seconds)
  "ext_expires_in": 86400,  // 🔄 Extended expiration time
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."  // 🎯 Use this in all API requests
}

Key Response Fields

Field	Description	Value
`access_token`	🎯 Use this in all API requests	JWT token string
`expires_in`	⏰ Token lifetime in seconds	`86400` (24 hours)
`ext_expires_in`	🔄 Extended expiration time	`86400` (24 hours)
`token_type`	🔑 Authentication type	Always `"Bearer"`

Token Management Best Practice: Cache tokens and refresh before expiry (24 hours). Implement token caching in your application to avoid unnecessary authentication requests.

Step 3: Validate Customer Access

Before processing any orders, always validate that the customer has access to place orders through your integration.

Why Validate?

Customer Validation Benefits

✅ Ensures customer is active in SRS system

✅ Retrieves customer code needed for subsequent calls

✅ Prevents failed orders due to invalid customers

✅ Returns customer details for verification

Customer Validation API Call

Endpoint: GET /customers/validate/

📤 Request Details - Click to expand

Request Headers:

Authorization: Bearer {token}

Content-Type: application/json

Query Parameters:

Parameter	Type	Required	Description
`accountNumber`	string	✅	Customer account number
`invoiceNumber`	string	⚠️ Optional	Invoice number for validation
`invoiceDate`	string	⚠️ Optional	Invoice date (YYYY-MM-DD)

Example Request:

✅ Response Example - Click to expand

{
  "validIndicator": "Y",  // 🔑 CRITICAL - Must be "Y" to proceed (not boolean!)
  "customerId": 46225,  // 🎯 Unique customer ID
  "accountNumber": "STO1170",  // 🎯 Save this for Step 5 (finding customer branches)
  "customerName": "STORM TEAM CONSTRUCTION INC",  // 👤 Display for user confirmation
  "homeBranchId": "3",  // 🏢 Default branch for this customer
  "customerAddress1": "4050 S US HWY 1",  // 📍 Customer address line 1
  "customerAddress2": "SUITE 303",  // 📍 Customer address line 2
  "customerAddress3": "",  // 📍 Customer address line 3 (optional)
  "customerCity": "JUPITER",  // 🏙️ Customer city
  "customerState": "FL",  // 🗺️ Customer state
  "customerZipCode": "33477",  // 📮 Customer zip code
  "customerPhone": "6146944583"  // 📞 Customer contact phone
}

Key Response Fields

Field	Description	Usage
`validIndicator`	🔑 CRITICAL - Must be `"Y"` (string!)	Validation status
`accountNumber`	🎯 Customer account code	Save for Step 5
`customerId`	🆔 Unique customer ID	Reference identifier
`customerName`	👤 Company name	Display to user
`homeBranchId`	🏢 Default branch ID	Preferred location
`customerAddress1-3`	📍 Street address	Shipping reference
`customerCity`	🏙️ City	Geographic data
`customerState`	🗺️ State code	Geographic data
`customerZipCode`	📮 ZIP/Postal code	Geographic data
`customerPhone`	📞 Contact number	Communication

Critical: Always check validIndicator === "Y" before proceeding with order flow. It's a string value, not boolean!

Step 4: Get Branch Locations

Explore available SRS branch locations to understand shipping options and coverage areas.

Why Get Branch Locations?

Branch Location Benefits

✅ See all available SRS branches

✅ Understand geographic coverage

✅ Display shipping options to users

✅ No prerequisites - safe to call anytime

Branch Locations API Call

Endpoint: GET /branches/v2/branchLocations

📤 Request Details - Click to expand

Request Headers:

Authorization: Bearer {token}

Content-Type: application/json

✅ Response Example - Click to expand

Branch Data Structure

[
  {
    "brandName": "SUNCOAST ROOFERS SUPPLY",  // 🏢 Brand identity
    "branchName": "SUNCOAST - PORT CHARLOTTE",  // 🏪 Display name
    "branchCode": "SRPCH",  // 🔑 Used in subsequent API calls (Step 6)
    "branchAddress": "23264 Harbor View Road",  // 📍 Street address
    "branchCity": "Port Charlotte",  // 🏙️ City
    "branchState": "FL",  // 🗺️ State
    "branchZip": "33980",  // 📮 Zip code
    "branchFax": "941-279-2804",  // 📠 Fax number
    "branchPhone": "941-279-2795",  // 📞 Phone number
    "shippingMethods": ["Ground Drop", "Roof Load"],  // 🚚 Available shipping options
    "salesTypes": {  // 📋 Order types supported
      "Delivery": "WHSE",
      "Pickup": "WILLCALL"
    },
    "businessHours": "MONDAY - FRIDAY, 7:00 AM TO 4:00 PM",  // ⏰ Operating hours
    "ordersEmail": "OrdersPortCharlotte@SuncoastRoofersSupply.com"  // 📧 Order contact email
  },
  {
    "brandName": "SUNCOAST ROOFERS SUPPLY",
    "branchName": "SUNCOAST - TAMPA",
    "branchCode": "SRTPA",
    "branchAddress": "5801 E Adamo Dr",
    "branchCity": "Tampa",
    "branchState": "FL",
    "branchZip": "33605",
    "branchFax": "813-241-8989",
    "branchPhone": "813-241-8900",
    "shippingMethods": ["Ground Drop", "Roof Load"],
    "salesTypes": {
      "Delivery": "WHSE",
      "Pickup": "WILLCALL"
    },
    "businessHours": "MONDAY - FRIDAY, 7:00 AM TO 4:00 PM",
    "ordersEmail": "OrdersTampa@SuncoastRoofersSupply.com"
  }
]

Key Response Fields

Field	Description	Usage
`branchCode`	🔑 Branch identifier	Use in Steps 6, 7, 8
`branchName`	🏪 Display name	Show to users
`branchAddress`	📍 Street address	Location info
`branchCity`	🏙️ City	Geographic filter
`branchState`	🗺️ State code	Geographic filter
`branchZip`	📮 ZIP code	Location lookup
`branchPhone`	📞 Contact number	Customer support
`branchFax`	📠 Fax number	Alternative contact
`shippingMethods`	🚚 Delivery options	Order configuration
`salesTypes`	📋 Order types	Pickup vs Delivery
`businessHours`	⏰ Operating hours	Scheduling
`ordersEmail`	📧 Order contact	Email notifications

✅ Checkpoint: What You've Accomplished

Congratulations! You've completed the foundational steps:

✅ Step 1: Obtained API credentials

✅ Step 2: Authenticated and retrieved access token

✅ Step 3: Validated a customer

✅ Step 4: Explored available branch locations

🏆 Skills You've Mastered - Click to expand

Technical Skills:

✅ OAuth 2.0 Client Credentials flow

✅ Bearer token authentication

✅ RESTful API calls (GET/POST)

✅ JSON request/response handling

✅ HTTP header management

✅ Error handling basics

Integration Knowledge:

✅ SRS API authentication workflow

✅ Customer validation process

✅ Branch location data structure

✅ Token lifecycle management

✅ Environment differences (Staging vs Production)

Data You Now Have:

🔑 Working access token (valid 24 hours)

👤 Valid customer code and account number

🏢 Complete list of SRS branch locations

📊 Understanding of API response structures

📊 Progress Assessment - Click to expand

You're ready for the next phase if:

Can successfully authenticate and get token

Token works in subsequent API calls

Can validate at least one customer

Retrieved branch locations successfully

Understand response data structure

Have basic error handling in place

Need more practice?

Try authenticating multiple times

Test with different customers

Explore all branch data fields

Implement token caching

Add logging and monitoring

Next Level Challenges:

Automate token refresh

Build customer search function

Create branch location finder

Implement comprehensive error handling

Set up integration testing suite

You now have:

Working authentication

Valid customer code

List of available branches

Understanding of API structure

🎯 Next Steps

You're ready to build complete order flows!

Continue to Place Order Guide

Place Order Guide - Steps 5-8

What you'll learn:

Step 5: Find customer-specific branches and job accounts

Step 6: Get available products at branches

Step 7: Get real-time pricing and availability

Step 8: Submit orders (sync or async)

Time to complete: 45-60 minutes

Troubleshooting Common Issues

🔑 Issue: Authentication fails (401 Unauthorized) - Click to expand

Symptoms:

HTTP 401 response

Error message: "Unauthorized" or "Invalid credentials"

Cannot get access token

Common Causes & Solutions:

❌ Wrong credentials

✅ Double-check client_id and client_secret

✅ Ensure no extra spaces or newlines

✅ Verify you're using the right credentials (not copy-paste errors)

❌ Wrong environment

✅ Staging credentials won't work in Production

✅ Verify base URL matches credential environment

✅ Check email from SRS for correct environment

❌ Missing or wrong grant_type

✅ Ensure grant_type is exactly "client_credentials"

✅ Check for typos: client_credential (singular) won't work

❌ Credentials expired or revoked

✅ Contact SRS API Support for new credentials

✅ Check if you requested credential rotation recently

Debug Checklist:

👤 Issue: Customer validation fails - Click to expand

Symptoms:

validIndicator is not "Y"

Customer not found error

Empty response or null values

Common Causes & Solutions:

❌ Customer identifier format

✅ Remove dashes, spaces, special characters

✅ Use exact format: "CUST12345" not "CUST-12345"

✅ Try different identifier types (code, email, account number)

❌ Customer not active in SRS system

✅ Verify customer account is active

✅ Contact SRS support to check customer status

✅ Customer may need onboarding to API access

❌ Customer not enabled for API

✅ Not all SRS customers have API access

✅ Contact SRS support to enable API for customer

✅ May require customer authorization

❌ Wrong environment

✅ Customer may exist in Production but not Staging

✅ Staging uses test customer data

✅ Try standard test customers for Staging

� Issue: Branch locations returns empty array - Click to expand

Symptoms:

Response is [] (empty array)

No branches returned

HTTP 200 but no data

Common Causes & Solutions:

❌ Token expired

✅ Verify token is still valid (< 24 hours old)

✅ Get new token and try again

✅ Check token expiry timestamp

❌ Wrong Authorization header format

✅ Must be: Authorization: Bearer YOUR_TOKEN

✅ Note the space after "Bearer"

✅ Token should not be wrapped in quotes in header

❌ Wrong environment/endpoint

✅ Verify base URL is correct

✅ Ensure endpoint path is exact: /branches/v2/branchLocations

✅ Check for typos in URL

Test with cURL:

Need Help?

📧 Contact SRS API Support Team - Click to expand

Email: APISupportTeam@srsdistribution.com

What to Include in Your Support Request:

✅ Your client ID (NOT the secret!)

✅ Environment (QA or Production)

✅ Error messages or response codes

✅ Request/response examples

✅ Steps to reproduce the issue

✅ What you've already tried

Response Time:

📅 Standard: 1-2 business days

🚨 Urgent (Production down): Same day

Urgent Issues:

Production outages

Authentication failures in Production

Order processing halted

Security concerns

For urgent issues, mark subject as: [URGENT]

📚 Self-Service Resources - Click to expand

Documentation:

📖 API Reference - Complete endpoint docs

📖 FAQ - Common questions answered

Tools:

🔧 APIdog Interactive Docs - Test live

🔧 Postman Collection - Download collection

🚀 Ready for the next phase? Proceed to the Place Order Guide to complete your integration!

Authentication

Getting Started with SIPS API#

🎯 What You'll Accomplish#

🔄 How Steps 1-4 Work Together#

Step 1: Request API Credentials#

Email Template#

What You'll Receive#

Step 2: Authenticate & Get Access Token#

What is OAuth 2.0 Client Credentials?#

Authentication Process#

Make Your First Authentication Request#

Step 3: Validate Customer Access#

Why Validate?#

Customer Validation API Call#

Step 4: Get Branch Locations#

Why Get Branch Locations?#

Branch Locations API Call#

Branch Data Structure#

✅ Checkpoint: What You've Accomplished#

🎯 Next Steps#

Place Order Guide - Steps 5-8#

Troubleshooting Common Issues#

Need Help?#

Getting Started with SIPS API

🎯 What You'll Accomplish

🔄 How Steps 1-4 Work Together

Step 1: Request API Credentials

Email Template

What You'll Receive

Step 2: Authenticate & Get Access Token

What is OAuth 2.0 Client Credentials?

Authentication Process

Make Your First Authentication Request

Step 3: Validate Customer Access

Why Validate?

Customer Validation API Call

Step 4: Get Branch Locations

Why Get Branch Locations?

Branch Locations API Call

Branch Data Structure

✅ Checkpoint: What You've Accomplished

🎯 Next Steps

Place Order Guide - Steps 5-8

Troubleshooting Common Issues

Need Help?