Connecting directly to the Salesforce API

This is a quick overview with instructions for each step of the process. 

Salesforce provides a more detailed (and often confusing) set of instructions for everything on this page here:

Step 1: Obtain an Authorization Code

Connect to the Salesforce Authorization Endpoint to retrieve a Code

This is a GET request to with the following query string attached:


So the full GET string would look like this:{{client_id}}&response_type=code&client_secret={{client_secret}}&redirect_uri={{redirect}}

The values vary between implementations. The values in red represent unresolved variables.

client_id and client_secret are implementation-specific and will be provided to you by a Mazo Capital Solutions representative.
response_type must always be code.
redirect_uri will always be

The endpoint will then direct you to a login screen

Log in using an authorized Salesforce Account. This will be provided to you by Mazo Capital Solutions.


A successful login will redirect you to the success page, with the Authorization Code you need in the GET request's query string

Like so:{{authorization_code}}

You'll need to take the code from the GET request in order to use it in the next step.


The code is returned as an URL-encoded string that will need to be converted. The last two characters are typically "==", which URL-encoding renders as "%3D%3D". You'll have to decode it in order to use it in Step 2 below.

Step 2: Obtain an Access Token

Send a POST request to the token endpoint


The endpoint is:

You MUST send a "Content-Type" header of "application/x-www-form-urlencoded" with the request.

An "Accept" header with the value "application/json" is optional, but can eliminate some obscure errors.
"Accept" can also be "*/*" though and it should still work fine. Only use "application/json" if there are problems.

The urlencoded form values are as follows:

grant_type => authorization_code
code => {{authorization_code}}
client_id => {{client_id}}
client_secret => {{client_secret}}
redirect_uri => {{redirect_uri}}
Once again, redirect_uri will always be

Success will return a JSON string similar to the following:

    "access_token" : "00D5Y000001N73m!AQwAQG078wf3SO14_dQ9t9V_3l9QLhEJFJkeWUDHNXX.fhun2IYhx0D4f.CQTz7A0RUMb3kTTNenkEqUn0G7iEOHsiQhxrJx",
    "issued_at" : "1652637409521",
    "instance_url" : "",
    "refresh_token" : "5Aep861NT6Ju45T6F1Yz6OTxnNfl_Srha9nKn.1EZT4enBlen5.v69k6e0M1xLVYMIjxfbcwJteHEJpScD42c6k"

Store the response

You'll need to refer to these values on an ongoing basis, so store them somewhere persistent, like a database or file.

Step 3: Create or Update a Lead

Now we're ready to create a Lead!

Connect to the "Lead" endpoint

You can now send a POST request to the Lead endpoint, which is at:


The value of {{instance_url}} is contained in the JSON response you stored in the previous step.

The instance URL will almost always be: "", but it's best practice to take it from the response above, as it's possible that some future iteration of the Salesforce REST API will change this.



The Access Token should be placed in an "Authorization" header, with the value "Bearer: {{access_token}}".

You'll need to send a "Content-Type" header of "application/json".

Lastly, you'll need to send the "client_id" header again.


The body/payload

Here's an example of a typical JSON body for creating a Mazo Capital Solutions lead:

    "FirstName": "Satisfied",
    "LastName": "Customer",
    "Title": "",
    "Company": "Example Inc.",
    "Street": "123 Example St. N",
    "City": "Austin",
    "State": "TX",
    "PostalCode": "78736",
    "Country": "United States",
    "Phone": "(555)-555-5555",
    "Email": "",
    "Website": "http:\/\/",
    "Description": "Building better buildings",
    "Status": "New",
    "AnnualRevenue": "600000",
    "OwnerId": "0055Y00000EVoLvQAL",
    "IsUnreadByOwner": true,
    "Follow_Up__c": "1",
    "Lead_Type__c": "Vendor Lead",
    "Years_In_Business__c": "1",
    "Street1__c": "123 Example st",
    "Federal_Tax_ID__c": "55-5555555",
    "Legal_Entity_Type__c": "Corporation",
    "First_Name1__c": "Satisfied",
    "Last_Name1__c": "Customer",
    "SSN1__c": "555-55-5555",
    "SSN2__c": "",
    "Title1__c": "",
    "Title2__c": "",
    "Phone1__c": "(555)-555-5555",
    "Phone2__c": "",
    "Ownership1__c": "100",
    "Ownership2__c": "",
    "Birthday1__c": "1955-05-05",
    "Birthday2__c": null,
    "Street2__c": "123 Example St. S",
    "First_Name2__c": "",
    "Last_Name2__c": "",
    "City2__c": "Austin",
    "City2_2__c": "",
    "Zip2__c": "55555",
    "Zip2_2__c": "55555",
    "State2__c": "TX",
    "State2_2__c": "",
    "Financing_Type__c": "Equipment Financing",
    "Amount_Requested__c": "9825",
    "Year__c": "2023",
    "Make__c": "PJ Trailers",
    "Model__c": "20x102",
    "TBD__c": "",
    "Time_Frame__c": "ASAP",
    "View_Terms__c": "I\/we have read and agree to these terms",
    "Dealer_ID__c": "0015Y00002aYV9NQAW",
    "Applicant_IP_Address__c": "",
    "Account__c": "0015Y00002aYV9NQAW",
    "Owners__c": "1",
    "What_Company_Does__c": "Building integrated solar roof sales and construction. (Solar shingle with curb appeal)",
    "WordPress_UniqueID__c": "52715",
    "Date_and_Time__c": "10\/27\/2022 - 08:39:49",
    "Use_of_funds__c": ""

Important Custom Fields

The field names that end in "__c" represent custom fields that have been added by Mazo Capital Solutions.

A few of these fields are important:

 "Dealer_ID__c" - this field should contain the Mazo Capital Solutions' Salesforce implementation's Account ID for the Dealer/Vendor. You can obtain it by asking your Mazo representative. This is the only way to automatically give credit for the Lead.

"View_Terms__c" - MUST be a checkbox filled in by the user with the value "I/we have read and agree to these terms". The words "these terms" in the form (not the JSON) should link to the Mazo Capital Solutions terms and conditions page at: "" or a verbatim copy on the Dealer/Vendor site.


A minimal payload is acceptable

In the example above, not all fields are required.

An example of a minimal payload that will still work is as follows:

    "FirstName": "Jimmy",
    "LastName": "Jimjo",
    "Phone": "013-345-6789",
    "Email": "",
    "Company": "Jimjo Jimmy Jo"


The success response will return something like the following:

    "id": "00Q4X00001vhja5555",
    "success": true,
    "errors": []
"id" is the Salesforce id for the newly-created Lead.


To indicate to the Lead endpoint that you are updating an existing Lead, simply append the id to the end of the request, like so:


The details of an update are exactly the same as for creation, except that for an update, send a PATCH request instead of a POST.

If access_token expires

The error response from Salesforce is inconsistent and dependent upon what you're trying to do, but an expired Access Token will return something like this:

"error": "invalid_grant",
"error_description": "expired access/refresh token"


"message":"Session expired or invalid",

Or any of a number of less relevant seeming responses that all amount to the same thing.

Refreshing an expired access_token

Step 2 returned a value, "refresh_token" in the JSON response.

You'll need to use this value with the refresh endpoint to get a new access token.

The endpoint is at

You send it the client id, client secret, and refresh token, and it responds with a new access token. You can send it either as headers using Basic authentication, or as the body of a POST request.

The refresh token flow is a single request and response, as opposed to the multi-part process of obtaining the initial token. Refresh token never expires.

Here's a link to the Salesforce documentation on refresh token flow:




In addition to the links above, the following files may prove useful.


Postman Collection

Postman Environment

PHP Example from Mazo Capital Solutions site

2022 Mazo Capital Solutions
linkedin facebook pinterest youtube rss twitter instagram facebook-blank rss-blank linkedin-blank pinterest youtube twitter instagram