API Example - Client Create

Problem

How do I create a Client (end-user) under my Partner account using the Partner API?
Creating a client end-user using the RESTful Partner API?

Solution

The following example of code shows you how to create a new client (end-user) under your partner account.

Prerequisites

To use the Partner API you must meet the following criteria

Have a working development environment.
Have an active Partner account. If you need a partner account you can sign up here.
Enabled your account to use the API and set the access controls.
Have valid API Credentials.
Optional - Setup your development environment to initially use the Sandbox Testing Portal.

For Partner API reference documentation please see https://portal.my-engine.com/apidocs/index.html

Example Code

The examples below uses the sandbox. For a production environment remember to change the following:

API Url
Partner ID
Partner API Key


<?php
/**
 * client-add.php
 * 
 * This example will Add a new client.
 * 
 */
$apiPartnerId = "<PartnerID>";
$apiSecretKey = "___PartnerKey___";

$apiUrl       = "https://sandbox.my-engine.com/api-v1/clients";


$crlf         = "<br />";

// Create the array for the new client data
$newClient    = array();

$newClient["external_userid"] = "123456789";     // Use this to link the My-Engine Client to your Solution.  This is the ID value of your record.
$newClient["email"] = "This email address is being protected from spambots. You need JavaScript enabled to view it.";
$newClient["username"] = "This email address is being protected from spambots. You need JavaScript enabled to view it.";
$newClient["title"] = "Mr";
$newClient["firstname"] = "Fred";
$newClient["surname"] = "Bloggs";

// Init Curl
$curl = curl_init();

// API Authentication:
curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($curl, CURLOPT_USERPWD, "$apiPartnerId:$apiSecretKey");

// Set Curl Options
curl_setopt($curl, CURLOPT_URL, $apiUrl);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);

// API POST DATA
curl_setopt($curl, CURLOPT_POST, 1);
curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($newClient));

// Tell it we're sending a JSON set of data in the POST
curl_setopt($curl, CURLOPT_HTTPHEADER, array(
    'Content-Type: application/json',
    ));

// API POST
$jsonResult = curl_exec($curl);

// Check for a valid HTTP 201 success and process the returned result
// or handler the failure.
if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) == 201) {
    $result = json_decode($jsonResult, true);

    if (json_last_error() == JSON_ERROR_NONE)   {
        echo "status = " . $result["meta"]["success"] . $crlf;
        echo "new client id = " . $result["data"]["id"] . $crlf;
        echo "client status = " . $result["data"]["client_status_id"] . $crlf;
        // Notice
    } else {
        print_r($result);
    }
    
} else {
    echo "Response Code = " . curl_getinfo($curl, CURLINFO_RESPONSE_CODE) . $crlf;
    
    $result = json_decode($jsonResult, true);
    if (json_last_error() == JSON_ERROR_NONE)   {
        echo "error = " . $result["error"]["name"] . $crlf;
        echo "url = " . $result["error"]["url"] . $crlf;
        echo "message = " . $result["error"]["message"] . $crlf;
    } else {
        echo $jsonResult;
    }
}

curl_close($curl);


/**
 * client-add.cs
 * 
 * This example will Add a new client.
 * 
 */


using Newtonsoft.Json;
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;

namespace clients_add
{
    class Program
    {
        private const string apiPartnerId = "<PartnerID>";
        private const string apiSecretKey = "_PartnerKey_";

        private const string apiUrl = "https://sandbox.my-engine.com/api-v1/clients";

        static void Main(string[] args)
        {
            // Create the new client data
            Dictionary<string, string> newClient = new Dictionary<string, string>();

            newClient.Add("external_userid", "123456789");      // Use this to link the My-Engine Client to your Solution.  This is the ID value of your record.
            newClient.Add("email", "This email address is being protected from spambots. You need JavaScript enabled to view it.");
            newClient.Add("username", "This email address is being protected from spambots. You need JavaScript enabled to view it.");
            newClient.Add("title", "Mr");
            newClient.Add("firstname", "Fred");
            newClient.Add("surname", "Bloggs");

            // Convert the Dictionary to Json
            string newClientJsonStr = JsonConvert.SerializeObject(newClient, Formatting.Indented);
            
            // Create HTTP resource
            HttpClient client = new HttpClient();

            // Add an Accept header for JSON format.
            client.DefaultRequestHeaders.Add("ContentType", "application/json");

            // Set the Authorisation
            var authToken = System.Text.Encoding.UTF8.GetBytes(apiPartnerId + ":" + apiSecretKey);
            client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", System.Convert.ToBase64String(authToken));

            // Create the content
            var content = new StringContent(newClientJsonStr, Encoding.UTF8, "application/json");

            // Do the POST
            var response = client.PostAsync(apiUrl, content).Result;

            // Check the result for a valid HTTP 201 success and process the returned result
            // or handler the failure.
            if (response.IsSuccessStatusCode)
            {
                // Get the created ID
                var jsonResponseStr = response.Content.ReadAsStringAsync().Result;
                dynamic jsonResponse = JsonConvert.DeserializeObject(jsonResponseStr);
                if (jsonResponse.ContainsKey("data"))
                {
                    Console.WriteLine("status = {0}", jsonResponse["meta"]["success"]);
                    Console.WriteLine("new client id = {0}", jsonResponse["data"]["id"]);
                    Console.WriteLine("client status = {0}", jsonResponse["data"]["client_status_id"]);
                }
                else
                {
                    Console.WriteLine("response = {0}", response); 
                    Console.WriteLine("json response = {0}", jsonResponse);
                }

            }
            else
            {
                // Get the Json Error response and convert it
                var jsonResponseStr = response.Content.ReadAsStringAsync().Result;
                dynamic jsonResponse = JsonConvert.DeserializeObject(jsonResponseStr);
                Console.WriteLine("name = {0}", jsonResponse["error"]["name"]);
                Console.WriteLine("url = {0}", jsonResponse["error"]["url"]);
                Console.WriteLine("message = {0}", jsonResponse["error"]["message"]);
                Console.WriteLine("{0} ({1})", (int)response.StatusCode, response.ReasonPhrase);
            }

            //Dispose once all HttpClient calls are complete.
            client.Dispose();
        }
    }
}


'
' client-add.vb
' 
' This example will Add a new client.
' 
'

Imports Newtonsoft.Json
Imports System.Net.Http
Imports System.Net.Http.Headers
Imports System.Text

Module Program

    Private Const apiPartnerId As String = "<PartnerID>"
    Private Const apiSecretKey As String = "_PartnerKey_"

    Private Const apiUrl As String = "https://sandbox.my-engine.com/api-v1/clients"

    Sub Main(args As String())

        ' Create the New client data
        Dim newClient As Dictionary(Of String, String) = New Dictionary(Of String, String)

        newClient.Add("external_userid", "123456789")      ' Use this to link the My-Engine Client to your Solution.  This is the ID value of your record.
        newClient.Add("email", "This email address is being protected from spambots. You need JavaScript enabled to view it.")
        newClient.Add("username", "This email address is being protected from spambots. You need JavaScript enabled to view it.")
        newClient.Add("title", "Mr")
        newClient.Add("firstname", "Fred")
        newClient.Add("surname", "Bloggs")

        ' Convert the Dictionary to Json
        Dim newClientJsonStr As String = JsonConvert.SerializeObject(newClient, Formatting.Indented)

        ' Create HTTP resource
        Dim client As New HttpClient()

        ' Add an Accept header for JSON format.
        client.DefaultRequestHeaders.Add("ContentType", "application/json")

        ' Set the Authorisation
        Dim authToken = System.Text.Encoding.UTF8.GetBytes(apiPartnerId + ":" + apiSecretKey)
        client.DefaultRequestHeaders.Authorization = New AuthenticationHeaderValue("Basic", System.Convert.ToBase64String(authToken))

        ' Create the content
        Dim content = New StringContent(newClientJsonStr, Encoding.UTF8, "application/json")

        ' Do the POST
        Dim response As HttpResponseMessage = client.PostAsync(apiUrl, content).Result

        ' Check the result for a valid HTTP 200 success And process the returned result
        ' Or handler the failure.
        If (response.IsSuccessStatusCode) Then
            ' Get the created ID
            Dim jsonResponseStr = response.Content.ReadAsStringAsync().Result
            Dim jsonResponse As Object = JsonConvert.DeserializeObject(jsonResponseStr)
            If jsonResponse.ContainsKey("data") Then
                Console.WriteLine("status = {0}", jsonResponse("meta")("success"))
                Console.WriteLine("new client id = {0}", jsonResponse("data")("id"))
                Console.WriteLine("client status = {0}", jsonResponse("data")("client_status_id"))
            Else
                Console.WriteLine("response = {0}", response)
                Console.WriteLine("json response = {0}", jsonResponse)
            End If
        Else
            ' Get the Json Error response And convert it
            Dim jsonResponseStr = response.Content.ReadAsStringAsync().Result
            Dim jsonResponse As Object = JsonConvert.DeserializeObject(jsonResponseStr)
            Console.WriteLine("name = {0}", jsonResponse("error")("name"))
            Console.WriteLine("url = {0}", jsonResponse("error")("url"))
            Console.WriteLine("message = {0}", jsonResponse("error")("message"))
            Console.WriteLine("{0} ({1})", response.StatusCode, response.ReasonPhrase)
        End If

        'Dispose once all HttpClient calls are complete.
        client.Dispose()

    End Sub

End Module


/**
 * client-add.js
 * 
 * This example will Add a new client.
 * 
 */

var apiPartnerId = "<PartnerID>";
var apiSecretKey = "_PartnerKey_";

var apiUrl = "https://sandbox.my-engine.com/api-v1/clients";

var jsondata = {
    "external_userid": "123456789", // Use this to link the My-Engine Client to your Solution.  This is the ID value of your record.
    "email": "This email address is being protected from spambots. You need JavaScript enabled to view it.",
    "username": "This email address is being protected from spambots. You need JavaScript enabled to view it.",
    "title": "Mr",
    "firstname": "Fred",
    "surname": "Bloggs"
};

// Setup the Ajax request
var settings = {
    url: apiUrl,
    headers: {
        'Authorization': 'Basic ' + btoa(apiPartnerId + ":" + apiSecretKey),
        'cache-control': 'no-cache'
    },
    crossDomain: true,
    // Uncomment the lines below if you want to POST data as JSON.
    //   If so comment the "data: jsondata" out
    //     contentType: 'application/json',
    //     data: JSON.stringify(jsondata),
    // Comment the line below out, if you've uncomment the two line above.
    //   The "data: jsondata" method will POST data as application/x-www-form-urlencoded
    data: jsondata,
    async: true,
    method: "POST"
};

// API POST
$.ajax(settings)
    .done(function(response) {
        console.log("status = " + response.meta.success);
        console.log("new client id = " + response.data.id);
        console.log("Client status = " + response.data.client_status_id);
        console.log(" ");

    })
    .fail(function(request, textStatus, errorThrown) {
        try {
            var errObj = $.parseJSON(request.responseText);
            console.log("API Error - " + errObj.name);
            console.log("API Msg   - " + errObj.message);
            console.log("API url   - " + errObj.url);
        } catch (e) {
            console.log("Error - " + errorThrown);
            console.log("Status - " + request.status);
            console.log(request);
        }
    });

API Example - Client Create

Problem

Solution

Prerequisites

Example Code

Did you enjoy this article?

Disclaimer

Email Services

Internet Services

Resources

Company

Search

API Example - Client Create

Problem

Solution

Prerequisites

Example Code

Did you enjoy this article?

Disclaimer