Org Directory Support

GitHub Copilot identity: Copilot reports by GitHub login, and by email only with EMU/SAML. Do we need a github_username column, or how is Copilot usage matched to a person?
Email matching: Is matching case-insensitive? The guide says "match exactly" but also "use lowercase".
Unmatched usage: Where does usage from emails missing from the directory show up (e.g. "Unassigned")?
History: Does a new file re-attribute past spend, or only spend from its effective date onward (point-in-time)?
id column: What if a customer has no HR employee ID? Can email be reused as id? How are duplicate ids handled?
Header rules and limits: Is a header row required? Are headers case-sensitive, and are spaces allowed? How are labels displayed in the UI? What are the max rows, file size and number of custom columns?
Rejected files: What validation runs, what the customer is told, and how long until data appears in Mavvrik.
Secure transfer and retention: Approved way to send the file (not plain email?), how long files are kept, and how deletion is requested.
Terminology: "Org Directory" vs "Org Taxonomy". Which name does the product UI use?
Connection: Is the connection created once and reused, or created per upload?
Connection fields: What are the name and source fields on the connection used for?
Status: What is the status endpoint, and what are its status values?

Org Directory: CSV Format Guide

Prepare a CSV file that maps your people to your organization. Mavvrik uses it to break down AI usage and spend by department, team, role and any other grouping you use.

What this file does

AI tools such as Claude, ChatGPT, GitHub Copilot and Cursor report usage and cost per user. Your org directory file adds your organizational context to each user. Once the file is loaded, you can filter and group AI spend and activity in Mavvrik by department, team, role and any custom attribute you include.

[Screenshot placeholder: AI spend grouped by Department, with the Org Directory attributes shown in the Filters / Group by menu.]

File format

CSV (comma-separated), UTF-8 encoded.
- Excel (Windows/Mac): File → Save As → CSV UTF-8 (Comma delimited).
- Google Sheets: File → Download → Comma-separated values (.csv).
The first row must be the header row.
One row per person. Each email must appear only once.
Leave a cell empty when you don't have a value. Don't use placeholders like N/A or -.
If a value contains a comma, wrap it in double quotes, for example "Brand, Content & Social". Excel and Google Sheets do this for you.
Columns can be in any order.
Include only the attributes you need for reporting. Don't include sensitive personal data such as salary or national ID numbers.

Tip: Excel removes leading zeros from numbers (00123 becomes 123). If your employee IDs start with zeros, format the id column as Text before you paste or type the values.

Standard columns

Column	Required?	Description	Example
`email`	Required	The email the person signs in to AI tools with. It links usage to the person, so it must match the email in those tools. Use lowercase.	jane.doe@example.com
`id`	Required	A unique, stable ID for the person, ideally your HR employee ID. It should stay the same even if their email changes.	E1001
`name`	Optional	Full name, shown in place of the email where available.	Jane Doe
`department`	Recommended	Department or business unit. This is the main grouping for spend reports.	Engineering
`team`	Recommended	Team or sub-group within the department.	Platform
`role`	Optional	Job title or role.	Senior Software Engineer

Additional columns (your own attributes)

You can add any other columns you want to report on, such as cost_center, location, manager_email, business_unit or legal_entity. Add each one as an extra column with a header name. Each becomes a filter and grouping option in Mavvrik, labeled with the header you chose.

Use short, clear header names. Every header must be unique.
All values are treated as text.
Empty cells are fine.

Sample file

Download the sample file below and use it as your starting template. Open it in Excel or Google Sheets, replace the example rows with your people, and save it as CSV UTF-8. In the sample, cost_center, location and manager_email are custom columns. A blank cell means the value isn't available.

org_directory_sample.csv

Sending updates

Send the complete, current list every time, not just the changes. We keep each file you send so we can track how your organization changes over time.
Send an updated file whenever your org changes, for example after a reorg, team moves, new hires or departures. A monthly refresh is enough for most teams. To track changes within a month, send a file every week.
Send the file to your Mavvrik Customer Success contact. [Confirm secure transfer method.]

Available now: you can upload your org directory file with the API and automate updates as often as daily. Follow the steps below.

Upload the file through the API

You can send your org directory file to Mavvrik directly from your own systems, with no email needed. This lets you automate uploads and send updates as often as daily.

Before you start

Your tenant ID (the part of your API address after the base URL).
An API key for your tenant. [CONFIRM: how to create one in Mavvrik, e.g. Settings > API Keys, and required role]
Your org directory file prepared as described in File format above.

Step 1: Get your API key

Sign in to Mavvrik as an admin.
Go to [CONFIRM: menu path] and create a new API key.
Copy the key and store it securely. It is shown only once. Never share it by email or commit it to source control.

Step 2: Set your variables

export MAVVRIK_API_KEY="<your-api-key>"
export MAVVRIK_URL="https://api.mavvrik.app/<your-tenant-id>"

Your API key is sent in the x-api-key header on every Mavvrik API call. [CONFIRM: base URL per environment]

Step 3: Check your file

Make sure the file is CSV UTF-8, has a header row with the required email and id columns, and has one row per person. See File format above.

Step 4: Upload the file

Uploading is three calls: create a connection, request a signed upload URL, then upload the file to that URL.

4a. Create a connection

Bash

curl -X POST "$MAVVRIK_URL/files/connections" \
  -H "x-api-key: $MAVVRIK_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "<label>", "source": "org-directory"}'

[CONFIRM: body fields; one connection reused or one per upload]

4b. Request a signed upload URL

Bash

curl -X POST "$MAVVRIK_URL/files/upload" \
  -H "x-api-key: $MAVVRIK_API_KEY" -H "Content-Type: application/json" \
  -d '{"connection_id": "<connection_id>", "files": [{"name": "org_directory-2026-10-07.csv", "size": 1398, "mimetype": "text/csv"}]}'

size is in bytes and mimetype must be text/csv. [CONFIRM: file naming rules]

4c. Upload to the signed URL

Bash

curl -X PUT "<signed-url>" -H "Content-Type: text/csv" --data-binary @org_directory.csv

Don’t send your API key to the signed URL. The URL expires after 60 minutes, and the Content-Type must match the mimetype requested.

Step 5: Check the responses

4a: HTTP 200 with id, name, source, provider_code (null), account_id (null), created_by, created, updated.

4b: HTTP 200 with an array of {id, name, url}. The id has the form <connection_id>/<file name>.

4c: HTTP 200 with an empty body. The file is stored.

Keep the connection id and file name to check the status.

Step 6: Check the upload status

Bash

curl "$MAVVRIK_URL/files" \
  -H "x-api-key: $MAVVRIK_API_KEY"

[CONFIRM: response, status values such as processing, completed and failed, and how errors are reported]

Once the status is completed, the new attributes appear as Filter and Group by options in Mavvrik. [CONFIRM: processing time]

Step 7: Automate your updates

Run the upload on a schedule from your HR system or a job scheduler. Always send the complete, current list, not just the changes. For example, a daily upload at 02:00 with cron:

0 2 * * * /path/to/upload_org_directory.sh

Limits and rules

Signed upload URLs expire after 60 minutes. Request a new one if it expires.
Maximum file size and number of rows: [CONFIRM]
Rate limit: [CONFIRM]
Each upload is kept so we can track how your organization changes over time.
The same file format rules apply as for emailed files.

Troubleshooting

Response	What it means and what to do
400 Bad Request	The file is not valid CSV UTF-8, the header row is missing, or the email or id column is missing. Fix the file and upload it again.
401 Unauthorized	The `x-api-key` header is missing, wrong or expired. Create a new key and try again.
403 Forbidden	The key does not have permission to upload org directory files. [CONFIRM]
413 Payload Too Large	The file is over the size limit. [CONFIRM]
422 Unprocessable	The file has duplicate emails or duplicate headers. Fix the file and upload it again.
429 Too Many Requests	You are sending uploads too often. Wait and retry.

If the upload to the signed URL (step 4c) fails with a 403 and an XML error, the URL has probably expired or the Content-Type did not match. Request a new URL (step 4b) and try again. [CONFIRM]

The 400, 403, 413 and 422 rows are unverified against the real API and still need testing. Content validation may happen after the PUT, so these errors may not come back from the upload calls.

Still stuck? Contact your Mavvrik Customer Success contact and include the connection ID and file name.

FAQ

What happens to AI usage from people who aren't in my file?

[Pending engineering: open question 3.]

Does a new file change how past spend is grouped?

[Pending engineering: open question 4.]

How should I handle contractors, service accounts, shared accounts or people with more than one email?

[Pending engineering. Suggested guidance: include contractors like employees; list each sign-in email as its own row with the same id if aliases are supported; put shared/service accounts under a dedicated department such as "Shared".]

How long until my data shows up, and what if the file has errors?

[Pending engineering: open question 7.]

Questions? Contact your Mavvrik Customer Success contact at any time.