CSV upload troubleshooting

Try these tips to solve common CSV upload issues

Here are some guides to help you identify and fix some common CSV upload issues. If you are still having trouble after following the steps below, contact [email protected] for help.

Is your CSV formatted correctly?

  1. Ensure the top row of your CSV includes all the required headers. These headers should include the parameter fields (such as userAttributes.[value]) for the data you're importing, separated by commas. Use a dot to indicate nested parameters. For example:


Then, ensure every row of your file is formatted to match these headers and has the same number of commas.

If a parameter field contains a comma as part of the value itself, then add a backslash before the comma. For example:



Make sure your attribute names follow these guides

Naming rules for events, states, user attributes, and parameters

  • Length must be greater than 0 and fewer than 140 characters.
  • Must not start with a period (.) or hyphen (-).
  • Must not end with a forward slash (/).
  • Must not contain commas (,), vertical pipes (|), double quotes ("), tabs, newlines, or return characters.
  • Must not be numeric.
  • Must not use the same name for different events and states, e.g. you should not name a state cart and an event cart.
  1. Check your spelling and capitalization β€” Leanplum-specific headers must be in camelCase (as in, "lastActive" and "userId").

  2. Make sure your file is named correctly. The file name cannot contain any spaces or special characters. (Underscores and dashes are OK, though.)

  3. Check for empty columns in the header row. You can check this by opening your CSV file in Sublime Text editor or a Numbers for Mac spreadsheet.

  4. Check the file for hidden symbols by opening it in VIM.

  1. Check the file's encoding to ensure it doesn't have a Byte Order Mark. To check the encoding, open the file in Sublime Text and click File > Save with Encoding > "UTF-8" (not "UTF-8 with BOM").


UserId whitespace

Leading and trailing whitespace in the userId column will not be trimmed. This can cause unintended new user profiles to be created if you are not careful.

Is your API call constructed correctly?

API calls require different keys and parameters. Make sure you're using the correct parameters for your call.

See the required parameters for each API call below:


multi(CSV) dev key

Remember that a multi(CSV) call requires your app's development key. Make sure you're not attempting the multi call with your prod key instead β€” that's used for JSON imports.

You can locate your keys here.

What was the response of your multi (CSV) call?

Perform a getMultiResults call to check the multi job results.

Your response will be one of these:

  • Pending. The job is still waiting in the queue and has not started processing yet.
  • Running. The job is currently being processed.
  • Finished. The job has finished. (This means the file has processed, not necessarily that the upload was 100% successful.)
  • Failed. The job failed before it could execute. The most common reason is Leanplum's backend could not read the file, perhaps due to file permissions or the file not being public.

To perform the getMultiResults call, you'll need the original multi call ID, found here:


You will get this jobId when you perform the initial multi call.

Your getMultiResults response will link you to a file detailing the status of each individual API call. This will help you troubleshoot where the file stopped working.

Still having issues?

Contact [email protected] for help troubleshooting your CSV upload.