PingCentral API Reference

Import Groups File

POST {{baseUrl}}/api/v1/groups/file

Use the POST {{baseUrl}}/api/v1/groups/file request to import a CSV file that lists groups to add. The CSV file can contain name, displayName, and description headings but only the name heading and values are required. As such, the following data would be properly formed in a CSV file:

"name","displayName","description"
"Marketing","MKTG",
"Manager",,
"Assistant",,"Assistant to the manager"

If desired, you can also just provide the required name values:

"name"
"Marketing"
"Manager"
"Assistant"

When you make this request, PingCentral automatically calls the validate request to check the file before import. If the validation fails, you will receive a 422 Unprocessable Entity code and none of the groups are added.

Headers

Authorization

Content-Type      multipart/form-data; boundary=<calculated when request is sent>

Cookie      <string>

X-XSRF-Header      PASS

Body

formdata

Key Type Value

file

text

<file>

Example Request

  • cURL

  • C#

  • Go

  • HTTP

  • Java

  • jQuery

  • NodeJS

  • Python

  • PHP

  • Ruby

  • Swift

curl --location --globoff '{{baseUrl}}/api/v1/groups/file' \
--header 'Cookie: <string>' \
--header 'X-XSRF-Header: PASS' \
--header 'Authorization: Basic e3t1c2VybmFtZX19Ont7cGFzc3dvcmR9fQ==' \
--form 'file="<file>"'
var options = new RestClientOptions("{{baseUrl}}/api/v1/groups/file")
{
  MaxTimeout = -1,
};
var client = new RestClient(options);
var request = new RestRequest("", Method.Post);
request.AddHeader("Cookie", "<string>");
request.AddHeader("X-XSRF-Header", "PASS");
request.AddHeader("Authorization", "Basic e3t1c2VybmFtZX19Ont7cGFzc3dvcmR9fQ==");
request.AlwaysMultipartFormData = true;
request.AddParameter("file", "<file>");
RestResponse response = await client.ExecuteAsync(request);
Console.WriteLine(response.Content);
package main

import (
  "fmt"
  "bytes"
  "mime/multipart"
  "net/http"
  "io"
)

func main() {

  url := "{{baseUrl}}/api/v1/groups/file"
  method := "POST"

  payload := &bytes.Buffer{}
  writer := multipart.NewWriter(payload)
  _ = writer.WriteField("file", "<file>")
  err := writer.Close()
  if err != nil {
    fmt.Println(err)
    return
  }


  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Cookie", "<string>")
  req.Header.Add("X-XSRF-Header", "PASS")
  req.Header.Add("Authorization", "Basic e3t1c2VybmFtZX19Ont7cGFzc3dvcmR9fQ==")

  req.Header.Set("Content-Type", writer.FormDataContentType())
  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := io.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}
POST /api/v1/groups/file HTTP/1.1
Host: {{baseUrl}}
Cookie: <string>
X-XSRF-Header: PASS
Authorization: Basic e3t1c2VybmFtZX19Ont7cGFzc3dvcmR9fQ==
Content-Length: 133
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="file"

<file>
------WebKitFormBoundary7MA4YWxkTrZu0gW--
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = new MultipartBody.Builder().setType(MultipartBody.FORM)
  .addFormDataPart("file","<file>")
  .build();
Request request = new Request.Builder()
  .url("{{baseUrl}}/api/v1/groups/file")
  .method("POST", body)
  .addHeader("Cookie", "<string>")
  .addHeader("X-XSRF-Header", "PASS")
  .addHeader("Authorization", "Basic e3t1c2VybmFtZX19Ont7cGFzc3dvcmR9fQ==")
  .addHeader("Content-Length", "")
  .build();
Response response = client.newCall(request).execute();
var form = new FormData();
form.append("file", "<file>");

var settings = {
  "url": "{{baseUrl}}/api/v1/groups/file",
  "method": "POST",
  "timeout": 0,
  "headers": {
    "Cookie": "<string>",
    "X-XSRF-Header": "PASS",
    "Authorization": "Basic e3t1c2VybmFtZX19Ont7cGFzc3dvcmR9fQ==",
    "Content-Length": ""
  },
  "processData": false,
  "mimeType": "multipart/form-data",
  "contentType": false,
  "data": form
};

$.ajax(settings).done(function (response) {
  console.log(response);
});
var request = require('request');
var options = {
  'method': 'POST',
  'url': '{{baseUrl}}/api/v1/groups/file',
  'headers': {
    'Cookie': '<string>',
    'X-XSRF-Header': 'PASS',
    'Authorization': 'Basic e3t1c2VybmFtZX19Ont7cGFzc3dvcmR9fQ==',
    'Content-Length': ''
  },
  formData: {
    'file': '<file>'
  }
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});
import requests

url = "{{baseUrl}}/api/v1/groups/file"

payload = {'file': '<file>'}
files=[

]
headers = {
  'Cookie': '<string>',
  'X-XSRF-Header': 'PASS',
  'Authorization': 'Basic e3t1c2VybmFtZX19Ont7cGFzc3dvcmR9fQ==',
  'Content-Length': ''
}

response = requests.request("POST", url, headers=headers, data=payload, files=files)

print(response.text)
<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('{{baseUrl}}/api/v1/groups/file');
$request->setMethod(HTTP_Request2::METHOD_POST);
$request->setConfig(array(
  'follow_redirects' => TRUE
));
$request->setHeader(array(
  'Cookie' => '<string>',
  'X-XSRF-Header' => 'PASS',
  'Authorization' => 'Basic e3t1c2VybmFtZX19Ont7cGFzc3dvcmR9fQ==',
  'Content-Length' => ''
));
$request->addPostParameter(array(
  'file' => '<file>'
));
try {
  $response = $request->send();
  if ($response->getStatus() == 200) {
    echo $response->getBody();
  }
  else {
    echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
    $response->getReasonPhrase();
  }
}
catch(HTTP_Request2_Exception $e) {
  echo 'Error: ' . $e->getMessage();
}
require "uri"
require "net/http"

url = URI("{{baseUrl}}/api/v1/groups/file")

http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Post.new(url)
request["Cookie"] = "<string>"
request["X-XSRF-Header"] = "PASS"
request["Authorization"] = "Basic e3t1c2VybmFtZX19Ont7cGFzc3dvcmR9fQ=="
request["Content-Length"] = ""
form_data = [['file', '<file>']]
request.set_form form_data, 'multipart/form-data'
response = http.request(request)
puts response.read_body
let parameters = [
  [
    "key": "file",
    "value": "<file>",
    "type": "text"
  ]] as [[String: Any]]

let boundary = "Boundary-\(UUID().uuidString)"
var body = Data()
var error: Error? = nil
for param in parameters {
  if param["disabled"] != nil { continue }
  let paramName = param["key"]!
  body += Data("--\(boundary)\r\n".utf8)
  body += Data("Content-Disposition:form-data; name=\"\(paramName)\"".utf8)
  if param["contentType"] != nil {
    body += Data("\r\nContent-Type: \(param["contentType"] as! String)".utf8)
  }
  let paramType = param["type"] as! String
  if paramType == "text" {
    let paramValue = param["value"] as! String
    body += Data("\r\n\r\n\(paramValue)\r\n".utf8)
  } else {
    let paramSrc = param["src"] as! String
    let fileURL = URL(fileURLWithPath: paramSrc)
    if let fileContent = try? Data(contentsOf: fileURL) {
      body += Data("; filename=\"\(paramSrc)\"\r\n".utf8)
      body += Data("Content-Type: \"content-type header\"\r\n".utf8)
      body += Data("\r\n".utf8)
      body += fileContent
      body += Data("\r\n".utf8)
    }
  }
}
body += Data("--\(boundary)--\r\n".utf8);
let postData = body


var request = URLRequest(url: URL(string: "{{baseUrl}}/api/v1/groups/file")!,timeoutInterval: Double.infinity)
request.addValue("<string>", forHTTPHeaderField: "Cookie")
request.addValue("PASS", forHTTPHeaderField: "X-XSRF-Header")
request.addValue("Basic e3t1c2VybmFtZX19Ont7cGFzc3dvcmR9fQ==", forHTTPHeaderField: "Authorization")
request.addValue("", forHTTPHeaderField: "Content-Length")
request.addValue("multipart/form-data; boundary=\(boundary)", forHTTPHeaderField: "Content-Type")

request.httpMethod = "POST"
request.httpBody = postData

let task = URLSession.shared.dataTask(with: request) { data, response, error in
  guard let data = data else {
    print(String(describing: error))
    return
  }
  print(String(data: data, encoding: .utf8)!)
}

task.resume()

Example Response

201 Created

{
  "groups": [
    {
      "created": "2020-12-03T12:52:25.973290Z",
      "description": "Description of the group.",
      "displayName": "All Employees",
      "id": "cd00f834-0c26-45ec-9410-cc38156cb4d4",
      "members": [
        {
          "firstName": "Default",
          "id": "cd00f834-0c26-45ec-9410-cc38156cb4d4",
          "lastName": "User",
          "source": "PASS-ISS",
          "username": "administrator"
        }
      ],
      "modified": "2020-12-03T12:52:25.973290Z",
      "name": "Company-Employees",
      "source": "PASS-ISS"
    }
  ]
}