DNA Match Inquiry API

Integration with our API introduces our members to your platform.

Introduction & Process

The Adopted.com DNA Match Inquiry API allows us check for a DNA match for our members within your platform. This provides our members with access to broader DNA data results, and it gives you the opportunity to acquire the member as a potential new customer.

The process of getting started as an Adopted.com DNA Match Inquiry partner is quite simple, with an emphasis on secure transmission of DNA data along with asynchronous results lookup.

  • 1

    The Adopted.com member requests DNA matches from our partners

    By clicking a checkbox to opt-in, our members indicate an interest in searching partner services (like yours) for relevant DNA matches.
  • 2

    We send the member's DNA data to your webhook

    Once you've setup and registered a webhook with us, we'll send the member's non-identifiable DNA data in a standardized, encrypted format over to you, along with a token representing the member within our system. We sign all requests so you know they came from us. Your webhook responds HTTP 200 to let us know you've received it.
  • 3

    You process the DNA data and determine if results are available

    You take the DNA data and decrypt it using our provided decryption method and your API key. You then process the DNA using whichever methods/systems you currently use. You will want to store the member's token during this process so you know who it belongs to.
  • 4

    You send the status of any results back to our API endpoint

    Once you've found potential matches or results, you let us know by sending a POST request to our API endpoint with the results status, the member's token, and a link to a landing page you assign to this program. You will need to authenticate and sign this request using our signing method.
  • 5

    If you have results available, we redirect the member to your assigned landing page

    If your request indicates that there are potential matches, we'll make the provided link available for our member to click-through to your assigned landing page - so that they can complete their registration with you and board as a member of your site under your terms and conditions.

Authentication

Every request sent to and from Adopted.com DNA Match Inquiry API must contain authentication information to establish the identity of the platform making the request. Our API uses authenticated POST requests to REST API endpoints, reducing latency while keeping data secure.

Important: Your API keys must remain secure.

Your API keys are unique to your partnership account with Adopted.com - we use it to verify that you are who you say you are, both in authentication headers and in the signature of every request. We highly recommend storing your keys in an encrypted manner while at rest. Your public key will be used in the Authorization header of all requests to us, and your secret key will be used locally when calculating request signatures. All code examples in this documentation have been pre-filled with your public/secret API keys for convenience.

Signed Requests

All requests that include or reference member data must be also be authenticated using a calculated signature. The signature is derived from applying sha-512 hashing to the member's token, the current date, and your secret API key - to ensure the validity of the request.

When you receive the initial data from us, you will want to calculate the signature and make sure they match, to ensure the request was sent from us. Likewise, when you respond with potential DNA matches, you'll need to include the calculated signature so that we know your response is valid. This signature will be a part of your JSON response.

Creating a Signature

PHP

copy

// This member token will be provided in the initial request from Adopted.com
$user_token = 'f974f450bbd44ad4ab01';

// This is your secret API key
$api_key = '51be2b27-5a00-47e7-b81c-0312facb9df4';

// Generate the signature of the member token using your API key and the current date
// The resulting signature is a 128-character string
$signature = hash_hmac('sha512', $user_token, $api_key.date("mmddyyyy"));

Setup & Register your Webhook

Your webhook URL is where we send all new requests from members to search for matching DNA data within your platform. To setup your webhook endpoint, you need to define a route on your server(s) for receiving the request, and then send a request to our registration endpoint to enable it.

  • 1

    Create a publically-accessible webhook endpoint

    This endpoint should only be accessible via SSL connection. It should only accept data if the POST variable `signature` matches the signature that you calculate on the fly using the POST variable `user_token` and your secret API key. Once you've verified the request, you will need to trigger your own process to begin DNA lookup (storing the user_token alongside) and respond HTTP 200 OK so that we know you've received this request.

    https://api.myendpointurl.com/webhook (PHP)

    copy
    
    
    // This is your secret API key
    $api_key = '51be2b27-5a00-47e7-b81c-0312facb9df4';
    
    // Generate the signature of the member token using your API key and the current date
    // The resulting signature is a 128-character string
    $signature = hash_hmac('sha512', $_POST["user_token"], $api_key.date("mmddyyyy"));
    
    // Check to make sure the signature we sent you is valid
    if(hash_equals($signature, $_POST["signature"])){
    	// Begin your DNA matching process, and let us know you've started
    	// Store the user_token alongside the request
    	// The DNA data is stored within $_POST["dna_encrypted"];
    	// See the section regarding DNA decryption (later in this document) to decrypt
    	http_response_code(200);
    }else{
    	// The signatures don't match, refuse the connection
    	http_response_code(401);
    }
    
  • 2

    Register your webhook endpoint with our servers

    Once you're happy with the way your webhook is setup, go ahead and send an authenticated POST request (no signature required) to our endpoint at
    https://partners.adopted.com/api/setup
    Make sure your request has the authorization header, and a single POST variable for the `endpoint` you want us to send requests to. We'll send you back a 200 OK if your webhook was registered. From now on, whenever a member requests potential DNA matches from our partners, you'll receive a POST request at your endpoint URI with their encrypted DNA data.

    PHP cURL

    copy
    
    $curl = curl_init();
    
    // Your webhook endpoint URL
    $endpoint = "https://api.myendpointurl.com/webhook";
    
    curl_setopt_array($curl, array(
      CURLOPT_URL => "https://partners.adopted.com/api/setup",
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_ENCODING => "",
      CURLOPT_MAXREDIRS => 10,
      CURLOPT_TIMEOUT => 30,
      CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
      CURLOPT_CUSTOMREQUEST => "GET",
      CURLOPT_POSTFIELDS => "endpoint=".urlencode($endpoint),
      CURLOPT_HTTPHEADER => array(
        "Content-Type: application/x-www-form-urlencoded",
        "Authorization: 0f408ac8-550e-499d-b208-a7c7d4fda885",
        "cache-control: no-cache"
      ),
    ));
    
    $response = curl_exec($curl);
    $err = curl_error($curl);
    
    curl_close($curl);
    

    NodeJS

    copy
    
    var request = require("request");
    
    var options = { method: 'GET',
      url: 'https://partners.adopted.com/api/setup',
      headers:
       { 'Authorization': '0f408ac8-550e-499d-b208-a7c7d4fda885',
         'cache-control': 'no-cache',
         'Content-Type': 'application/x-www-form-urlencoded' },
      form: { endpoint: 'https://api.myendpointurl.com/webhook' } };
    
    request(options, function (error, response, body) {
      if (error) throw new Error(error);
    
      console.log(body);
    });
    

    HTTP Request

    copy
    
    GET /api/setup HTTP/1.1
    Host: partners.adopted.com
    Content-Type: application/x-www-form-urlencoded
    cache-control: no-cache
    Authorization: 0f408ac8-550e-499d-b208-a7c7d4fda885
    endpoint=https%3A%2F%2Fapi.myendpointurl.com%2Fwebhook
    

Processing DNA Data

We understand that searching for matches among DNA data takes time and resources, which is why we've split the request/response when it comes to notifying an Adopted.com member of their results. Your initial webhook simply responds 200 OK that you've received the request, and then the real fun begins. This is where you take the data and search for results within your own platform.

Naturally, every partner searches for results their own way, using their own methods - but before you do, you'll need to decrypt the DNA data we've sent you. As mentioned earlier, the DNA data is stored within the POST variable `dna_encrypted` using an AES-256-CTR encryption. Let's take a look at how to decrypt that:

PHP

copy

// This is your secret API key
$api_key = '51be2b27-5a00-47e7-b81c-0312facb9df4';

// Base 64 Decode the Original Data
$original_data = base64_decode($_POST["encrypted_dna"]);

// Prepare the Initialization Vector
$iv_length = openssl_cipher_iv_length("AES-256-CTR");
$iv = substr($original_data, 0, $iv_length);

// Decrypt using OpenSSL AES-256-CTR
$decrypted_dna_data = openssl_decrypt($original_data, "AES-256-CTR", $api_key, OPENSSL_RAW_DATA, $iv);

////////////////////////////////////////////////////////////////////////////////////////////
// Now you can look for matches using the standardized DNA data in $decrypted_dna_data... //
////////////////////////////////////////////////////////////////////////////////////////////

Sending the Response

Let's skip ahead and say that you've completed the DNA matching process. When ready, it's time to let the Adopted.com memeber know whether or not you have potential matches for them.

  • 1

    Prepare the JSON-formatted response

    The Adopted.com servers expect properly-formatted JSON data in your response. You don't need to send complicated data back - simply the member's token along with a boolean value for whether or not matches exist, and a URL that you want us to send the member to in order to be boarded to your platform in whatever manner is customary for you. You will also need to include a signature representing the the member's token (see the "creating a signature" section). It's important that you only say that you have matches if you actually do - as we'll show the member that a match exists prior to sending them to your landing page.

    JSON

    copy
    
    {
      "user_token": "f974f450bbd44ad4ab01",
      "matches_exist": "true",
      "redirect_URI": "https://www.mywebsite.com/register/",
      "signature": "d199tg7pewobfsoszxsjeru7a8.......etc..."
    }
    
  • 2

    Send the JSON data to our endpoint

    Once you've got the JSON ready to go, send the signed and authenticated POST request to our endpoint at:
    https://partners.adopted.com/api/matches
    We'll send you back a 200 OK if everything checks out, or a 401 if your signature or authorization header are missing/invalid, or if we can't find the user_token on our end. Do not send PII (personally identifiable information) or your secret API key back with this request.

    PHP cURL

    copy
    
    $curl = curl_init();
    
    curl_setopt_array($curl, array(
      CURLOPT_URL => "https://partners.adopted.com/api/matches",
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_ENCODING => "",
      CURLOPT_MAXREDIRS => 10,
      CURLOPT_TIMEOUT => 30,
      CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
      CURLOPT_CUSTOMREQUEST => "GET",
      CURLOPT_POSTFIELDS => json_encode($my_response_data), // See JSON formatting example above
      CURLOPT_HTTPHEADER => array(
        "Content-Type: application/json",
        "Authorization: 0f408ac8-550e-499d-b208-a7c7d4fda885",
        "cache-control: no-cache",
        'Content-Length: ' . strlen(json_encode($my_response_data))
      ),
    ));
    
    $response = curl_exec($curl);
    $err = curl_error($curl);
    
    curl_close($curl);
    

Success

If you've got this far, you've successfully setup your webhook, received a request from us to process DNA data, and submitted DNA match data back to our platform. Adopted.com members can now start to extend their search to your platform, and can be ensured that you have an appropriate match for them prior to beginning the registration process.

Please contact us if you have any problems or need assistance integrating with our DNA Lookup Partner API - we'd be glad to help!

- The Adopted.com Team