service-direct/php-partners-sdk

A simple PHP library to integrate with Service Direct's Partners API

v1.1.1 2024-07-10 19:35 UTC

README

Overview:

The purpose of this SDK it to ease the integration process for our affiliates who use PHP.

See full documentation for our APIs here:

Install this library using Composer:

composer require service-direct/php-partners-sdk

Response Codes

The API responds with different HTTP status codes to better rely the result of a call. These response codes include 200, 400, 404, etc. If your system is senstive to different response codes, the suppress_response_codes variable can be added to every response URL (e.g. /partners/request?suppress_response_codes) to always return a 200 HTTP status code.

The intended HTTP status code will be returned in the x-original-status-code header.

Endpoints

The SDK integrates with the following API endpoints:

  • Phones

    • POST /partners/request - request a phone bid
    • POST /partners/request/{request_id}/accept - accept a phone bid
      • This API endpoint should only be requested if the phone number is intended to be called.
    • POST /partners/request/{request_id}/sold_price - report the sold price a different buyer (other than Service Direct) paid
  • Forms

    • POST /partners/forms/ping - request a form bid
    • POST /partners/forms/{lead_token}/post - accept a form bid
    • POST /partners/forms/{lead_token}/sold_price - report a lost bid winning price

As well as the following dynamically changing open endpoints to get Service Direct's latest availabilities:

Examples

The SDK includes 6 example files to help facilitate your integration. In the example file, replace the placeholder value with your private Key to start testing.

use ServiceDirect\Partners\PartnersClient;

$key = '[YOUR_KEY_HERE]';

$client = new PartnersClient($key);
  • Contact Service Direct in order to obtain your Private Key.
  • This string must be kept hidden and treated like any other private credentials or passwords.
  • Your Key is required in the Phones and Forms endpoints
  • In all the example files, the optional value of test_mode is set to true

Phones

Using this SDK, a Publisher Partner who generates phone calls and wants to sell those leads to Service Direct can request a bid from Service Direct’s clients by submitting a request with a service category and zip code to POST /partners/request.

See [1] examples/request-bid.php

Then, if our client's bid is satisfactory, the Partner can accept the bid and receive a forwarding tracking phone number to route the caller to the winning client by sending a request to POST /partners/request/{request_id}/accept.

See [2] examples/request-accept.php

If, however, a different buy (other than Service Direct) won your lead, you can notify Service Direct of the sold price by sending a request to POST /partners/request/{request_id}/sold_price.

See [3] examples/request-sold-price.php

Forms

Using this API, a Publisher Partner who generates form leads and wants to sell those leads to Service Direct can request a bid from Service Direct's clients by submitting a request with a service category, zip code, and a TCPA consent to POST /partners/forms/ping.

See [4] examples/form-ping.php

Then, if our client's bid is satisfactory, the Partner can accept the bid and receive a confirmation message by sending a request to POST /partners/forms/{lead_token}/post.

See [5] examples/form-post.php

If our client's bid is unsatisfactory, the Partner can report the winning bid and receive a confirmation message by sending a request to POST /partners/forms/{lead_token}/post.

See [6] examples/form-sold-price.php

General

Publisher Partners can use our supporting endpoints to determine their best integration options:

The response (for both options) will be in the following format:

{
  "data": {
    "service_categories": [
      {
        "id":"20",
        "industry_master_id":"4",
        "name":"Plumbing"
      },
      {
        "id":"2",
        "industry_master_id":"1",
        "name":"Air Conditioning"
      },
      ...
    ],
    "master_service_categories": [
      /* not for this SDK purposes */
      ...
    ]
  }
}
  • Do you have current coverage in this zip code? What is the maximum CPL available in this zip code?
    • Send an API request to https://api.servicedirect.com/cpl/industry/{service_category_id}

Response for service category 2 - Air Conditioning:

{
  "data": {
    "industry_name": "Air Conditioning",
    "zip_codes": [
      {
        "zip_code":"32957",
        "max_cpl":"65.00"
      },
      {
        "zip_code":"32958",
        "max_cpl":"65.00"
      },
      {
        "zip_code":"32962",
        "max_cpl":"65.00"
      },
      ...
    ]
  }
}

Fur further assistance please contact support@servicedirect.com