Connecting directly to the Salesforce API

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

https://help.salesforce.com/s/articleView?id=sf.remoteaccess_oauth_web_server_flow.htm&type=5&language=en_US

This is a GET request to https://login.salesforce.com/services/oauth2/authorize with the following query string attached:

?client_id={{client_id}}&response_type=code&client_secret={{client_secret}}&redirect_uri={{redirect}}

So the full GET string would look like this:

https://login.salesforce.com/services/oauth2/authorize?client_id={{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 https://mazocapital2021.my.salesforce.com/services/oauth2/success

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

Like so:

https://mazocapital2021.my.salesforce.com/services/oauth2/success?code={{authorization_code}}

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

Note:

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.

The endpoint is:

https://mazocapital2021.my.salesforce.com/services/oauth2/token

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 https://mazocapital2021.my.salesforce.com/services/oauth2/success

Success will return a JSON string similar to the following:

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

Now we're ready to create a Lead!

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

{{instance_url}}/services/data/v54.0/sobjects/Lead

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

The instance URL will almost always be: "https://mazocapital2021.my.salesforce.com", 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.

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

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: "https://mazocapital.com/terms-and-conditions/" or a verbatim copy on the Dealer/Vendor site.

In the example above, not all fields are required.

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

The success response will return something like the following:

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:

{{instance_url}}/services/data/v54.0/sobjects/Lead/{{id}}

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.

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"
}

or

{
"message":"Session expired or invalid",
"errorCode":"INVALID_SESSION_ID"
}

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

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

https://login.salesforce.com/services/oauth2/token

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:

https://help.salesforce.com/s/articleView?id=sf.remoteaccess_oauth_refresh_token_flow.htm&type=5

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

Postman Collection

Postman Environment

PHP Example from Mazo Capital Solutions site