Queue document imports from a CSV mapping
Stages uploaded document files and dispatches ImportDocumentsWithCsvJob to attach them to recipients or donors using a previously uploaded CSV. The request identifies CSV columns for unique-field matching, source filenames, and permissions. Requires admin file access through user.permissions.
curl --request POST \
--url https://api.gratona.com/v1/admin/import_files/{type}/{program_id}/import-documents \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: multipart/form-data' \
--form csv_filename=imports/documents.csv \
--form csv_unique_field_column=0 \
--form csv_filename_column=1 \
--form csv_permission_column=2 \
--form unique_field=hys_id \
--form files=@example-file \
--form create_thumbnails=falseimport requests
url = "https://api.gratona.com/v1/admin/import_files/{type}/{program_id}/import-documents"
files = { "files": ("example-file", open("example-file", "rb")) }
payload = {
"csv_filename": "imports/documents.csv",
"csv_unique_field_column": "0",
"csv_filename_column": "1",
"csv_permission_column": "2",
"unique_field": "hys_id",
"create_thumbnails": "false"
}
headers = {"Authorization": "Bearer <token>"}
response = requests.post(url, data=payload, files=files, headers=headers)
print(response.text)const form = new FormData();
form.append('csv_filename', 'imports/documents.csv');
form.append('csv_unique_field_column', '0');
form.append('csv_filename_column', '1');
form.append('csv_permission_column', '2');
form.append('unique_field', 'hys_id');
form.append('files', '<string>');
form.append('create_thumbnails', 'false');
const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};
options.body = form;
fetch('https://api.gratona.com/v1/admin/import_files/{type}/{program_id}/import-documents', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.gratona.com/v1/admin/import_files/{type}/{program_id}/import-documents",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"csv_filename\"\r\n\r\nimports/documents.csv\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"csv_unique_field_column\"\r\n\r\n0\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"csv_filename_column\"\r\n\r\n1\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"csv_permission_column\"\r\n\r\n2\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"unique_field\"\r\n\r\nhys_id\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"files\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"create_thumbnails\"\r\n\r\nfalse\r\n-----011000010111000001101001--",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: multipart/form-data"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.gratona.com/v1/admin/import_files/{type}/{program_id}/import-documents"
payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"csv_filename\"\r\n\r\nimports/documents.csv\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"csv_unique_field_column\"\r\n\r\n0\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"csv_filename_column\"\r\n\r\n1\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"csv_permission_column\"\r\n\r\n2\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"unique_field\"\r\n\r\nhys_id\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"files\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"create_thumbnails\"\r\n\r\nfalse\r\n-----011000010111000001101001--")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.gratona.com/v1/admin/import_files/{type}/{program_id}/import-documents")
.header("Authorization", "Bearer <token>")
.body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"csv_filename\"\r\n\r\nimports/documents.csv\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"csv_unique_field_column\"\r\n\r\n0\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"csv_filename_column\"\r\n\r\n1\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"csv_permission_column\"\r\n\r\n2\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"unique_field\"\r\n\r\nhys_id\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"files\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"create_thumbnails\"\r\n\r\nfalse\r\n-----011000010111000001101001--")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.gratona.com/v1/admin/import_files/{type}/{program_id}/import-documents")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"csv_filename\"\r\n\r\nimports/documents.csv\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"csv_unique_field_column\"\r\n\r\n0\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"csv_filename_column\"\r\n\r\n1\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"csv_permission_column\"\r\n\r\n2\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"unique_field\"\r\n\r\nhys_id\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"files\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"create_thumbnails\"\r\n\r\nfalse\r\n-----011000010111000001101001--"
response = http.request(request)
puts response.read_body{
"message": "Document import job has been queued. You will be notified when the import is complete."
}{
"message": "Not Found",
"status": "error"
}{
"errors": {},
"status": "error",
"message": "The given data was invalid."
}{
"message": "Something went wrong. Please try again.",
"status": "error",
"error": "invalid_request",
"code": "DONOR_NOT_FOUND"
}Authorizations
Passport bearer token authentication for legacy admin sessions.
Path Parameters
Required path value identifying which record type the documents should attach to. Accepted values are entity and donor; invalid values return 422.
entity, donor Required program ID used by the queued document import job to scope matching for the current client.
Body
Required string. S3 filename of the CSV mapping file already uploaded for this import.
"imports/documents.csv"
Required numeric zero-based CSV column index containing the recipient or donor unique field value.
x >= 00
Required numeric zero-based CSV column index containing each source document filename.
x >= 01
Required numeric zero-based CSV column index containing the desired file permission value.
x >= 02
Required string. Field key used to match each CSV row to a recipient or donor.
"hys_id"
Required document uploads staged for the background import. Each file must pass the configured document import size limit.
Optional boolean. When true, the job may create thumbnails for image-like documents.
false
Response
Document import job queued.
"Document import job has been queued. You will be notified when the import is complete."
curl --request POST \
--url https://api.gratona.com/v1/admin/import_files/{type}/{program_id}/import-documents \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: multipart/form-data' \
--form csv_filename=imports/documents.csv \
--form csv_unique_field_column=0 \
--form csv_filename_column=1 \
--form csv_permission_column=2 \
--form unique_field=hys_id \
--form files=@example-file \
--form create_thumbnails=falseimport requests
url = "https://api.gratona.com/v1/admin/import_files/{type}/{program_id}/import-documents"
files = { "files": ("example-file", open("example-file", "rb")) }
payload = {
"csv_filename": "imports/documents.csv",
"csv_unique_field_column": "0",
"csv_filename_column": "1",
"csv_permission_column": "2",
"unique_field": "hys_id",
"create_thumbnails": "false"
}
headers = {"Authorization": "Bearer <token>"}
response = requests.post(url, data=payload, files=files, headers=headers)
print(response.text)const form = new FormData();
form.append('csv_filename', 'imports/documents.csv');
form.append('csv_unique_field_column', '0');
form.append('csv_filename_column', '1');
form.append('csv_permission_column', '2');
form.append('unique_field', 'hys_id');
form.append('files', '<string>');
form.append('create_thumbnails', 'false');
const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};
options.body = form;
fetch('https://api.gratona.com/v1/admin/import_files/{type}/{program_id}/import-documents', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.gratona.com/v1/admin/import_files/{type}/{program_id}/import-documents",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"csv_filename\"\r\n\r\nimports/documents.csv\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"csv_unique_field_column\"\r\n\r\n0\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"csv_filename_column\"\r\n\r\n1\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"csv_permission_column\"\r\n\r\n2\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"unique_field\"\r\n\r\nhys_id\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"files\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"create_thumbnails\"\r\n\r\nfalse\r\n-----011000010111000001101001--",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: multipart/form-data"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.gratona.com/v1/admin/import_files/{type}/{program_id}/import-documents"
payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"csv_filename\"\r\n\r\nimports/documents.csv\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"csv_unique_field_column\"\r\n\r\n0\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"csv_filename_column\"\r\n\r\n1\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"csv_permission_column\"\r\n\r\n2\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"unique_field\"\r\n\r\nhys_id\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"files\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"create_thumbnails\"\r\n\r\nfalse\r\n-----011000010111000001101001--")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.gratona.com/v1/admin/import_files/{type}/{program_id}/import-documents")
.header("Authorization", "Bearer <token>")
.body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"csv_filename\"\r\n\r\nimports/documents.csv\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"csv_unique_field_column\"\r\n\r\n0\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"csv_filename_column\"\r\n\r\n1\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"csv_permission_column\"\r\n\r\n2\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"unique_field\"\r\n\r\nhys_id\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"files\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"create_thumbnails\"\r\n\r\nfalse\r\n-----011000010111000001101001--")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.gratona.com/v1/admin/import_files/{type}/{program_id}/import-documents")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"csv_filename\"\r\n\r\nimports/documents.csv\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"csv_unique_field_column\"\r\n\r\n0\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"csv_filename_column\"\r\n\r\n1\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"csv_permission_column\"\r\n\r\n2\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"unique_field\"\r\n\r\nhys_id\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"files\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"create_thumbnails\"\r\n\r\nfalse\r\n-----011000010111000001101001--"
response = http.request(request)
puts response.read_body{
"message": "Document import job has been queued. You will be notified when the import is complete."
}{
"message": "Not Found",
"status": "error"
}{
"errors": {},
"status": "error",
"message": "The given data was invalid."
}{
"message": "Something went wrong. Please try again.",
"status": "error",
"error": "invalid_request",
"code": "DONOR_NOT_FOUND"
}