General Tips

If you are using an API Client like Postman, you can use the Import feature to convert cURL (from docs.janrain.com) to Postman-compliant JSON. Alternatively, you can convert Postman calls to other code formats (Python, PHP, Javascript, and many more)
You may opt to use a 3rd party JSON validator (many are available via Google Search). Keep in mind that sensitive information (PII, API Client/Owner Secrets, etc.) should not be entered into such tools.
If you see { "message": "Internal Server Error" } after attempting to make an API call, the most likely cause is that a variable has not been completed in the end point call, for example: :flow must be updated to reflect the actual name of the flow
Passing a dictionary of key, value pairs: A JSON dictionary (often also referred to an JSON object) is a grouping of key and value pairs wrapped in braces ({“key1”: “stringValue”, “key2”: [“listValue1”, “listValue2”], “key3”: {“nestedKey1”: “nestedValue1”}})
Passing a list of items: In JSON a list is grouping of other syntactically valid JSON objects wrapped in brackets ([ “value1”, {“key1”: “value2”}, ...]). All inner objects must be also bevalid JSON types, separated by a comma, with no trailing comma.
When passing JSON as a query parameter Postman will automatically recognize the format and make the appropriate escapes to be passed as a parameter. Keep this in mind. Pending on the language you are working in you may need to import a library to do this or create a method that can do so.

Common Query Parameter Errors

"JSON is not syntactically valid"

There are a number of parameters that expect the passed value to be passed in JSON format. When receiving this error the best troubleshooting method is to paste your parameter into a JSON linting tool. One of the most confusing reason for this error is when you are passing a single value. For a single string value to be syntactically valid in JSON it needs to be wrapped in double quotes (“) and nothing else.

Error Example:

/entity.Update

{
   "argument_name": "value",
   "request_id": "zmheh9jbvrnb3qvr",
   "code": 200,
   "error_description": "value was not valid for the following reason: the JSON is not syntactically valid",
   "error": "invalid_argument",
   "stat": "error"
}

Correction:

"Filter was not valid for the following reason: not syntactically valid"

It is good to keep in mind that Postman is trying to be helpful by wrapping query parameters in quotes, when can lead to unexpected errors when you need to include quotes within your parameter. When running into this error you may need to try a few different combinations of quote types and spaces to achieve a similar result to the CURL examples

Example Error:

/entity.find

{
   "argument_name": "filter",
   "request_id": "697mukbwezywbt9k",
   "code": 200,
   "error_description": "filter was not valid for the following reason: not syntactically valid",
   "error": "invalid_argument",
   "stat": "error"
}

Correction:

Avoiding Common JSON Syntax Errors

We often receive questions from customers after receiving syntax errors in API clients (such as Postman):

Syntax may differ across different Janrain API endpoints. The following are our most commonly used endpoints.

Adding a new Schema attribute (/entity.AddAttribute)
Adding a new API Client (/clients/add)
Adding a new field to the Flow (/config.../field)
Adding a new field to a Form in the Flow (/config.../form)
Updating an existing Mail Template (/config.../template)
Counting Filtered Records in your Profile Registration Database (/entity.count)
Examining Filtered Records in your Profile Registration Database (/entity.find)

Adding a new Schema attribute:

Goal: To add a new attribute called “favoriteTeam” to the “user” schema.
Parameters: “Type_name” and “attr_def” are required parameters within the call, as follows:
API Method and URL: POST: https://{{capture_domain}}.janraincapture.com/entityType.addAttribute?type_name=user&attr_def={"name":"favoriteTeam","type":"string","length":50}

Adding a new API Client:

Goal: To add a new API login client called “newTestClient” to the “user” schema.
Parameters: “description” and “features” are required parameters within the call, as follows:
API Method and URL: POST: https://{{capture_domain}}.janraincapture.com/clients/add?description=newTestClient&features=["login_client"]

Adding a new field to the flow:

Goal: To add a new field called “myCustomTextField” to a specific flow.
Parameters: “region”, “app_id”, “flow-name” and “locale” values are required values within the call, as follows:
API Method and URL: POST: https://v1.api.us.janrain.com/config/736sdsd78bd/flows/standard/locales/en-US/fields

(this example uses the Body field within the Postman API client)

{
 "type": "text",
 "name": "myCustomTextField",
 "schemaAttribute": "displayName",
 "label": "foo",
 "tip": "foo",
 "socialProfileData": "profile.displayName",
 "placeholder": "foo",
 "validation": [
   {
     "rule": "required",
     "value": true,
     "message": "foo"
   },
   {
     "rule": "unique",
     "value": true,
     "message": "foo"
   }
 ]
}

Adding a field to a form in the flow:

Goal: To map a newly added field to a specific form (or forms).
Parameters: “region”, “app_id”, “flow-name” and “locale” values are required values within the call, as follows:
API Method and URL: PUT: https://v1.api.us.janrain.com/config/736sdsd78bd/flows/standard/forms/registrationForm

(this example uses the Body field within the Postman API client - you must include the full content of the email for this endpoint, not just the portion that you want to update)

{
   "_self": "/config/<<app-id>>/flows/<<flow-name>>/forms/<<form-name>>",
   "fields": [
       {
           "_self": "/config/<<redacted>>/flows/<<flow-name>>/fields/firstName",
           "required": true,
           "name": "firstName"
       },
       {
           "_self": "/config/<<app-id>>/flows/<<flow-name>>/fields/middleName",
           "required": false,
           "name": "middleName"
       },
       {
           "_self": "/config/<<app-id>>/flows/<<flow-name>>/fields/addressCountry",
           "required": false,
           "name": "addressCountry"
       }
   ]
}

Updating an existing mail template:

Goal: To modify an existing mail template to include revised language.
Parameters: “region”, “app_id”, “flow-name”, “locale” and “mail-template” values are required within the call, as follows:
API Method and URL: PUT: https://v1.api.us.janrain.com/config/736sdsd78bd/flows/standard/locales/en-US/mailTemplates/registrationConfirmation