CSVBox import webhook (called by CSVBox, not the client)

curl --request POST \
  --url http://localhost/mogl/mogl-backend/api/agent/roster-imports/csvbox \
  --header 'Content-Type: application/json' \
  --header 'X-Import-Token: <api-key>' \
  --data '
[
  {
    "row_number": 1,
    "row_data": {
      "first_name": "Alex",
      "last_name": "Patel",
      "email": "alex@example.edu",
      "phone": "5551234567",
      "sport": "Football",
      "school": "University of California",
      "graduation_year": "2027",
      "dob": "2005-04-12",
      "gender": "Male",
      "us_citizen": "Y",
      "hometown": "Newark, NJ",
      "jersey_no": "12",
      "height": 70,
      "weight": 185,
      "bio": "Junior wide receiver.",
      "profile_photo_url": "https://example.com/photos/alex.jpg"
    },
    "import_id": 79418895,
    "sheet_id": 55,
    "sheet_name": "MOGL Agent Roster Import - Development",
    "total_rows": 1,
    "env_name": "development",
    "original_filename": "roster.csv",
    "custom_fields": {
      "user_id": "1002"
    }
  }
]
'

import requests

url = "http://localhost/mogl/mogl-backend/api/agent/roster-imports/csvbox"

payload = [
    {
        "row_number": 1,
        "row_data": {
            "first_name": "Alex",
            "last_name": "Patel",
            "email": "alex@example.edu",
            "phone": "5551234567",
            "sport": "Football",
            "school": "University of California",
            "graduation_year": "2027",
            "dob": "2005-04-12",
            "gender": "Male",
            "us_citizen": "Y",
            "hometown": "Newark, NJ",
            "jersey_no": "12",
            "height": 70,
            "weight": 185,
            "bio": "Junior wide receiver.",
            "profile_photo_url": "https://example.com/photos/alex.jpg"
        },
        "import_id": 79418895,
        "sheet_id": 55,
        "sheet_name": "MOGL Agent Roster Import - Development",
        "total_rows": 1,
        "env_name": "development",
        "original_filename": "roster.csv",
        "custom_fields": { "user_id": "1002" }
    }
]
headers = {
    "X-Import-Token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-Import-Token': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify([
    {
      row_number: 1,
      row_data: {
        first_name: 'Alex',
        last_name: 'Patel',
        email: 'alex@example.edu',
        phone: '5551234567',
        sport: 'Football',
        school: 'University of California',
        graduation_year: '2027',
        dob: '2005-04-12',
        gender: 'Male',
        us_citizen: 'Y',
        hometown: 'Newark, NJ',
        jersey_no: '12',
        height: 70,
        weight: 185,
        bio: 'Junior wide receiver.',
        profile_photo_url: 'https://example.com/photos/alex.jpg'
      },
      import_id: 79418895,
      sheet_id: 55,
      sheet_name: 'MOGL Agent Roster Import - Development',
      total_rows: 1,
      env_name: 'development',
      original_filename: 'roster.csv',
      custom_fields: {user_id: '1002'}
    }
  ])
};

fetch('http://localhost/mogl/mogl-backend/api/agent/roster-imports/csvbox', 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 => "http://localhost/mogl/mogl-backend/api/agent/roster-imports/csvbox",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    [
        'row_number' => 1,
        'row_data' => [
                'first_name' => 'Alex',
                'last_name' => 'Patel',
                'email' => 'alex@example.edu',
                'phone' => '5551234567',
                'sport' => 'Football',
                'school' => 'University of California',
                'graduation_year' => '2027',
                'dob' => '2005-04-12',
                'gender' => 'Male',
                'us_citizen' => 'Y',
                'hometown' => 'Newark, NJ',
                'jersey_no' => '12',
                'height' => 70,
                'weight' => 185,
                'bio' => 'Junior wide receiver.',
                'profile_photo_url' => 'https://example.com/photos/alex.jpg'
        ],
        'import_id' => 79418895,
        'sheet_id' => 55,
        'sheet_name' => 'MOGL Agent Roster Import - Development',
        'total_rows' => 1,
        'env_name' => 'development',
        'original_filename' => 'roster.csv',
        'custom_fields' => [
                'user_id' => '1002'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-Import-Token: <api-key>"
  ],
]);

$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 := "http://localhost/mogl/mogl-backend/api/agent/roster-imports/csvbox"

	payload := strings.NewReader("[\n  {\n    \"row_number\": 1,\n    \"row_data\": {\n      \"first_name\": \"Alex\",\n      \"last_name\": \"Patel\",\n      \"email\": \"alex@example.edu\",\n      \"phone\": \"5551234567\",\n      \"sport\": \"Football\",\n      \"school\": \"University of California\",\n      \"graduation_year\": \"2027\",\n      \"dob\": \"2005-04-12\",\n      \"gender\": \"Male\",\n      \"us_citizen\": \"Y\",\n      \"hometown\": \"Newark, NJ\",\n      \"jersey_no\": \"12\",\n      \"height\": 70,\n      \"weight\": 185,\n      \"bio\": \"Junior wide receiver.\",\n      \"profile_photo_url\": \"https://example.com/photos/alex.jpg\"\n    },\n    \"import_id\": 79418895,\n    \"sheet_id\": 55,\n    \"sheet_name\": \"MOGL Agent Roster Import - Development\",\n    \"total_rows\": 1,\n    \"env_name\": \"development\",\n    \"original_filename\": \"roster.csv\",\n    \"custom_fields\": {\n      \"user_id\": \"1002\"\n    }\n  }\n]")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Import-Token", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("http://localhost/mogl/mogl-backend/api/agent/roster-imports/csvbox")
  .header("X-Import-Token", "<api-key>")
  .header("Content-Type", "application/json")
  .body("[\n  {\n    \"row_number\": 1,\n    \"row_data\": {\n      \"first_name\": \"Alex\",\n      \"last_name\": \"Patel\",\n      \"email\": \"alex@example.edu\",\n      \"phone\": \"5551234567\",\n      \"sport\": \"Football\",\n      \"school\": \"University of California\",\n      \"graduation_year\": \"2027\",\n      \"dob\": \"2005-04-12\",\n      \"gender\": \"Male\",\n      \"us_citizen\": \"Y\",\n      \"hometown\": \"Newark, NJ\",\n      \"jersey_no\": \"12\",\n      \"height\": 70,\n      \"weight\": 185,\n      \"bio\": \"Junior wide receiver.\",\n      \"profile_photo_url\": \"https://example.com/photos/alex.jpg\"\n    },\n    \"import_id\": 79418895,\n    \"sheet_id\": 55,\n    \"sheet_name\": \"MOGL Agent Roster Import - Development\",\n    \"total_rows\": 1,\n    \"env_name\": \"development\",\n    \"original_filename\": \"roster.csv\",\n    \"custom_fields\": {\n      \"user_id\": \"1002\"\n    }\n  }\n]")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://localhost/mogl/mogl-backend/api/agent/roster-imports/csvbox")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["X-Import-Token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "[\n  {\n    \"row_number\": 1,\n    \"row_data\": {\n      \"first_name\": \"Alex\",\n      \"last_name\": \"Patel\",\n      \"email\": \"alex@example.edu\",\n      \"phone\": \"5551234567\",\n      \"sport\": \"Football\",\n      \"school\": \"University of California\",\n      \"graduation_year\": \"2027\",\n      \"dob\": \"2005-04-12\",\n      \"gender\": \"Male\",\n      \"us_citizen\": \"Y\",\n      \"hometown\": \"Newark, NJ\",\n      \"jersey_no\": \"12\",\n      \"height\": 70,\n      \"weight\": 185,\n      \"bio\": \"Junior wide receiver.\",\n      \"profile_photo_url\": \"https://example.com/photos/alex.jpg\"\n    },\n    \"import_id\": 79418895,\n    \"sheet_id\": 55,\n    \"sheet_name\": \"MOGL Agent Roster Import - Development\",\n    \"total_rows\": 1,\n    \"env_name\": \"development\",\n    \"original_filename\": \"roster.csv\",\n    \"custom_fields\": {\n      \"user_id\": \"1002\"\n    }\n  }\n]"

response = http.request(request)
puts response.read_body

{
  "data": {
    "id": 12,
    "status": "queued"
  }
}

[
  {
    "type": "cell",
    "row_id": 3,
    "column": "email",
    "message": "Email already exists"
  }
]

{
  "message": "Unauthenticated."
}

{
  "message": "This upload could not be read."
}

CSVBox import webhook (called by CSVBox, not the client)

The CSVBox sheet’s API destination, with Server Side Validation on. CSVBox posts the submitted rows here; this one call both validates and accepts. Sheet setup: chunk size of at least 1000 (the whole file in one request), Results Page set to not close on import complete, and resubmission of All Rows, so each row keeps its row_number. *

- Any error: HTTP 211 with the errors as CSVBox cell errors (row_id = CSVBox row_number, column = the sheet column). CSVBox shows the fail screen and takes the agent back to its grid to correct and resubmit. Nothing is written: no import, no athlete, no notification.
- No error: the rows are persisted as the session’s import and queued, then HTTP 200. A 200 means only that MOGL accepted the batch; completion is the import’s own terminal status.
- A repeated delivery under a session that was already accepted returns 200 with the same import and creates nothing.
Required, matching athlete signup: first_name, last_name (max 255), email, phone (10 digits, the athlete’s own), sport (name) or sport_category_id, school (name) or university_id, graduation_year (4 digits), dob, gender (Male, Female or Prefer not to say), us_citizen (Y/N). Optional: hometown, jersey_no (max 10), height, weight, bio (max 5000), profile_photo_url. Other keys are ignored.
A bad required field is an error on its cell. A bad optional field never is: the file is accepted, that field is left empty, and the row’s message in the results says which fields were skipped and why (CSVBox has no warnings).
profile_photo_url (http or https) is downloaded in the background after the athlete is added: JPEG, PNG or WebP, up to 25 MB, public addresses only. If it cannot be used, the athlete keeps no photo and the reason is added to the row’s message. A photo the athlete already has is never replaced.
An email or phone that already belongs to a MOGL account is an error, never a link, with athlete signup’s own messages on the field that is taken: Email already exists (email) and This phone number is already being used by an existing user (phone). The agent invites existing athletes by email instead. A shared test phone is refused. An athlete already on this agent’s roster is not an error: they are not duplicated, only their empty fields are filled. An email or phone that repeats within the file is an error on every occurrence. A sport or school that does not match one of MOGL’s by name is an error on that cell: The sport "X" was not found. or The school "X" was not found.
Every rule is checked again when each row is provisioned, since an account can change in between; such a row fails in the results and can be retried. More than 1000 rows, or a file that arrives in parts, is a table error. Rate limit 60/min.

POST

agent

roster-imports

csvbox

CSVBox import webhook (called by CSVBox, not the client)

curl --request POST \
  --url http://localhost/mogl/mogl-backend/api/agent/roster-imports/csvbox \
  --header 'Content-Type: application/json' \
  --header 'X-Import-Token: <api-key>' \
  --data '
[
  {
    "row_number": 1,
    "row_data": {
      "first_name": "Alex",
      "last_name": "Patel",
      "email": "alex@example.edu",
      "phone": "5551234567",
      "sport": "Football",
      "school": "University of California",
      "graduation_year": "2027",
      "dob": "2005-04-12",
      "gender": "Male",
      "us_citizen": "Y",
      "hometown": "Newark, NJ",
      "jersey_no": "12",
      "height": 70,
      "weight": 185,
      "bio": "Junior wide receiver.",
      "profile_photo_url": "https://example.com/photos/alex.jpg"
    },
    "import_id": 79418895,
    "sheet_id": 55,
    "sheet_name": "MOGL Agent Roster Import - Development",
    "total_rows": 1,
    "env_name": "development",
    "original_filename": "roster.csv",
    "custom_fields": {
      "user_id": "1002"
    }
  }
]
'

import requests

url = "http://localhost/mogl/mogl-backend/api/agent/roster-imports/csvbox"

payload = [
    {
        "row_number": 1,
        "row_data": {
            "first_name": "Alex",
            "last_name": "Patel",
            "email": "alex@example.edu",
            "phone": "5551234567",
            "sport": "Football",
            "school": "University of California",
            "graduation_year": "2027",
            "dob": "2005-04-12",
            "gender": "Male",
            "us_citizen": "Y",
            "hometown": "Newark, NJ",
            "jersey_no": "12",
            "height": 70,
            "weight": 185,
            "bio": "Junior wide receiver.",
            "profile_photo_url": "https://example.com/photos/alex.jpg"
        },
        "import_id": 79418895,
        "sheet_id": 55,
        "sheet_name": "MOGL Agent Roster Import - Development",
        "total_rows": 1,
        "env_name": "development",
        "original_filename": "roster.csv",
        "custom_fields": { "user_id": "1002" }
    }
]
headers = {
    "X-Import-Token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-Import-Token': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify([
    {
      row_number: 1,
      row_data: {
        first_name: 'Alex',
        last_name: 'Patel',
        email: 'alex@example.edu',
        phone: '5551234567',
        sport: 'Football',
        school: 'University of California',
        graduation_year: '2027',
        dob: '2005-04-12',
        gender: 'Male',
        us_citizen: 'Y',
        hometown: 'Newark, NJ',
        jersey_no: '12',
        height: 70,
        weight: 185,
        bio: 'Junior wide receiver.',
        profile_photo_url: 'https://example.com/photos/alex.jpg'
      },
      import_id: 79418895,
      sheet_id: 55,
      sheet_name: 'MOGL Agent Roster Import - Development',
      total_rows: 1,
      env_name: 'development',
      original_filename: 'roster.csv',
      custom_fields: {user_id: '1002'}
    }
  ])
};

fetch('http://localhost/mogl/mogl-backend/api/agent/roster-imports/csvbox', 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 => "http://localhost/mogl/mogl-backend/api/agent/roster-imports/csvbox",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    [
        'row_number' => 1,
        'row_data' => [
                'first_name' => 'Alex',
                'last_name' => 'Patel',
                'email' => 'alex@example.edu',
                'phone' => '5551234567',
                'sport' => 'Football',
                'school' => 'University of California',
                'graduation_year' => '2027',
                'dob' => '2005-04-12',
                'gender' => 'Male',
                'us_citizen' => 'Y',
                'hometown' => 'Newark, NJ',
                'jersey_no' => '12',
                'height' => 70,
                'weight' => 185,
                'bio' => 'Junior wide receiver.',
                'profile_photo_url' => 'https://example.com/photos/alex.jpg'
        ],
        'import_id' => 79418895,
        'sheet_id' => 55,
        'sheet_name' => 'MOGL Agent Roster Import - Development',
        'total_rows' => 1,
        'env_name' => 'development',
        'original_filename' => 'roster.csv',
        'custom_fields' => [
                'user_id' => '1002'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-Import-Token: <api-key>"
  ],
]);

$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 := "http://localhost/mogl/mogl-backend/api/agent/roster-imports/csvbox"

	payload := strings.NewReader("[\n  {\n    \"row_number\": 1,\n    \"row_data\": {\n      \"first_name\": \"Alex\",\n      \"last_name\": \"Patel\",\n      \"email\": \"alex@example.edu\",\n      \"phone\": \"5551234567\",\n      \"sport\": \"Football\",\n      \"school\": \"University of California\",\n      \"graduation_year\": \"2027\",\n      \"dob\": \"2005-04-12\",\n      \"gender\": \"Male\",\n      \"us_citizen\": \"Y\",\n      \"hometown\": \"Newark, NJ\",\n      \"jersey_no\": \"12\",\n      \"height\": 70,\n      \"weight\": 185,\n      \"bio\": \"Junior wide receiver.\",\n      \"profile_photo_url\": \"https://example.com/photos/alex.jpg\"\n    },\n    \"import_id\": 79418895,\n    \"sheet_id\": 55,\n    \"sheet_name\": \"MOGL Agent Roster Import - Development\",\n    \"total_rows\": 1,\n    \"env_name\": \"development\",\n    \"original_filename\": \"roster.csv\",\n    \"custom_fields\": {\n      \"user_id\": \"1002\"\n    }\n  }\n]")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Import-Token", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("http://localhost/mogl/mogl-backend/api/agent/roster-imports/csvbox")
  .header("X-Import-Token", "<api-key>")
  .header("Content-Type", "application/json")
  .body("[\n  {\n    \"row_number\": 1,\n    \"row_data\": {\n      \"first_name\": \"Alex\",\n      \"last_name\": \"Patel\",\n      \"email\": \"alex@example.edu\",\n      \"phone\": \"5551234567\",\n      \"sport\": \"Football\",\n      \"school\": \"University of California\",\n      \"graduation_year\": \"2027\",\n      \"dob\": \"2005-04-12\",\n      \"gender\": \"Male\",\n      \"us_citizen\": \"Y\",\n      \"hometown\": \"Newark, NJ\",\n      \"jersey_no\": \"12\",\n      \"height\": 70,\n      \"weight\": 185,\n      \"bio\": \"Junior wide receiver.\",\n      \"profile_photo_url\": \"https://example.com/photos/alex.jpg\"\n    },\n    \"import_id\": 79418895,\n    \"sheet_id\": 55,\n    \"sheet_name\": \"MOGL Agent Roster Import - Development\",\n    \"total_rows\": 1,\n    \"env_name\": \"development\",\n    \"original_filename\": \"roster.csv\",\n    \"custom_fields\": {\n      \"user_id\": \"1002\"\n    }\n  }\n]")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://localhost/mogl/mogl-backend/api/agent/roster-imports/csvbox")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["X-Import-Token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "[\n  {\n    \"row_number\": 1,\n    \"row_data\": {\n      \"first_name\": \"Alex\",\n      \"last_name\": \"Patel\",\n      \"email\": \"alex@example.edu\",\n      \"phone\": \"5551234567\",\n      \"sport\": \"Football\",\n      \"school\": \"University of California\",\n      \"graduation_year\": \"2027\",\n      \"dob\": \"2005-04-12\",\n      \"gender\": \"Male\",\n      \"us_citizen\": \"Y\",\n      \"hometown\": \"Newark, NJ\",\n      \"jersey_no\": \"12\",\n      \"height\": 70,\n      \"weight\": 185,\n      \"bio\": \"Junior wide receiver.\",\n      \"profile_photo_url\": \"https://example.com/photos/alex.jpg\"\n    },\n    \"import_id\": 79418895,\n    \"sheet_id\": 55,\n    \"sheet_name\": \"MOGL Agent Roster Import - Development\",\n    \"total_rows\": 1,\n    \"env_name\": \"development\",\n    \"original_filename\": \"roster.csv\",\n    \"custom_fields\": {\n      \"user_id\": \"1002\"\n    }\n  }\n]"

response = http.request(request)
puts response.read_body

{
  "data": {
    "id": 12,
    "status": "queued"
  }
}

[
  {
    "type": "cell",
    "row_id": 3,
    "column": "email",
    "message": "Email already exists"
  }
]

{
  "message": "Unauthenticated."
}

{
  "message": "This upload could not be read."
}

Authorizations

X-Import-Token

string

header

required

The import_token from POST /agent/roster-imports/session. The client passes it to the CSVBox importer in request_headers, and CSVBox sends it on every delivery to the import webhook. Encrypted with this environment's app key; it names the agent, the session and the environment.

Body

application/json

CSVBox's JSON delivery: one object per row.

Maximum array length: 1000

row_number

integer

required

Becomes the row's row_number in the results.

Example:

1

row_data

object

required

Show child attributes

import_id

integer

CSVBox's import id; new on every resubmission. Not used as the idempotency key.

Example:

79418895

sheet_id

integer

Example:

55

sheet_name

string

Example:

"MOGL Agent Roster Import - Development"

total_rows

integer

Rows in the whole file. Must equal the number of rows in this request, or the file is reported as arriving in parts.

Example:

1

env_name

string

Example:

"development"

original_filename

string

Example:

"roster.csv"

custom_fields

object

From the importer's setUser; not trusted for authorization.

Show child attributes

Response

Accepted and queued, or already accepted under this session

data

object

Show child attributes

Core API

University API

Notifications API

CSVBox import webhook (called by CSVBox, not the client)

Authorizations

Body

Response