Uploading and Access File Attachments

Upload files to profile fields and retrieve attachment contents using the Graphite Connect Public API.

Before You Begin

You’ll need:

  • A bearer token obtained using the Authentication guide.
  • API permissions to read or update the target profile and file field.
  • The file field’s answer key, as defined in your API mapping.
  • The company’s public ID when accessing a connected company’s profile.

The examples below use Example_File as a placeholder answer key. Replace it with the answer key for your file field.

All examples use this production base URL:

https://app.graphiteconnect.com/api/public/api/v1

Use your environment’s hostname when working outside production.

Choosing a Profile

Use the same profile endpoint for uploads and reads:

TargetEndpoint
Your company’s own profile/profile
A connected company’s profile/profile/{publicId}

The examples below target a connected company. To use your own profile, omit /{publicId}.

Uploading a File

To upload an attachment, send a PATCH request with the file field’s answer key and an object containing:

PropertyDescription
fileNameThe original filename, including its extension.
fileContentsBase64The file’s bytes encoded as base64.

Use standard padded base64 without line breaks or a data: prefix. Send the answer map directly in the JSON body, without an answers wrapper.

curl --request PATCH \
  'https://app.graphiteconnect.com/api/public/api/v1/profile/YOUR_PUBLIC_ID' \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "Example_File": {
      "fileName": "example.txt",
      "fileContentsBase64": "SGVsbG8K"
    }
  }'

This example uploads a text file containing Hello followed by a newline.

For a real attachment, base64-encode the original file’s bytes and use the resulting string as fileContentsBase64.

Uploading Multiple Files

For a field configured to accept multiple files, provide an array of upload objects:

{
  "Example_Files": [
    {
      "fileName": "first.txt",
      "fileContentsBase64": "Rmlyc3QK"
    },
    {
      "fileName": "second.txt",
      "fileContentsBase64": "U2Vjb25kCg=="
    }
  ]
}

Only use an array for fields that support multiple attachments.

Uploading replaces the field’s current attachment selection. A multiple-file upload replaces the selection with the submitted files; it does not append them. Replacing an attachment reference does not delete the previously stored file.

Reading Attachment Metadata

Retrieve a file field using GET with the answerKeys query parameter:

curl --get \
  'https://app.graphiteconnect.com/api/public/api/v1/profile/YOUR_PUBLIC_ID' \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --data-urlencode 'answerKeys=Example_File'

The response includes attachment metadata. For example:

{
  "Example_File": {
    "fileId": "FILE_ID",
    "filename": "example.txt",
    "mimeType": "text/plain",
    "fileSize": 6,
    "hasThumbnail": false
  }
}

A multiple-file field returns an array of attachment objects.

The read response uses filename, while uploads use fileName. Do not submit the metadata object as an upload payload.

Retrieving File Contents

Add includeFileContents=true to include attachment bytes as base64 in the profile response:

curl --get \
  'https://app.graphiteconnect.com/api/public/api/v1/profile/YOUR_PUBLIC_ID' \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --data-urlencode 'answerKeys=Example_File' \
  --data-urlencode 'includeFileContents=true' \
  --output profile-files.json

The attachment object includes fileContentsBase64:

{
  "Example_File": {
    "fileId": "FILE_ID",
    "filename": "example.txt",
    "mimeType": "text/plain",
    "fileSize": 6,
    "hasThumbnail": false,
    "fileContentsBase64": "SGVsbG8K"
  }
}

Decode fileContentsBase64 to recover the original file bytes. For example, using Python:

import base64
import json
from pathlib import Path

profile = json.loads(Path("profile-files.json").read_text())
attachment = profile["Example_File"]

contents = attachment.get("fileContentsBase64")
if contents is None:
    raise RuntimeError("File contents were not returned.")

Path("downloaded-example.txt").write_bytes(
    base64.b64decode(contents, validate=True)
)

For a multiple-file field, decode each object in the returned array separately.

Use answerKeys to request only the fields you need, especially when including file contents. Base64 increases the response size by approximately one third.

Verifying an Upload

After uploading, read the same field to confirm its filename and metadata. Include includeFileContents=true if you also need to verify the stored bytes.

If an upload times out or returns an uncertain result, read the field before retrying. The upload may have completed, and submitting it again can create another stored file.

Troubleshooting

IssueWhat to check
Authentication or access failureConfirm that the token is valid and has permission to access the target profile and field.
Upload rejectedCheck the answer key, filename, base64 encoding, and whether the field accepts one or multiple files.
Request too largeCheck the environment’s request and file-size limits. Base64 adds approximately one third to the original file size.
Metadata returned without file contentsConfirm includeFileContents=true. File contents can also be absent if the file cannot be accessed or read.
URL returned instead of file contentsA file-or-URL field may contain a URL reference. Saving a URL does not upload the linked file’s bytes.

Treat attachment contents as sensitive data. Avoid writing bearer tokens or base64 file contents to application logs.


Did this page help you?