Grouping with Collections

Collections in FSCO provide a way to organize and group related documents together. Common uses include:

• Organizing documents by department (HR documents, Legal contracts, Financial reports)
• Grouping documents by project or client
• Creating sets of templates for different business processes
• Managing document versions and revisions
• Bundling related forms and agreements together

This guide will walk you through creating and updating collections using our API.

Prerequisites

Before you begin, ensure you have:

• A valid FSCO API key
• Your application’s environment configured with the API key

Create a Collection

Endpoint

POST /v2/document/collection

Request Parameters

{
  "name": "Your Collection Name",
  "description": "Optional description of the collection"
}

The request requires:

• name: A descriptive name for your collection
• description: (Optional) A description of what the collection contains

Example Request

cURL

create-collection.sh

#!/bin/bash

curl -X POST https://api.fsco.io/v2/document/collection \
  -H "x-api-key: $FSCO_API_KEY" \
  -H "x-api-secret: $FSCO_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Your Collection Name",
    "description": "Optional description of the collection"
  }'

TypeScript

create-collection.ts

import axios from 'axios';

const apiKey = process.env.FSCO_API_KEY;
const apiSecret = process.env.FSCO_API_SECRET;
const baseURL = 'https://api.fsco.com/v2';

async function createCollection() {
  try {
    const response = await axios.post(
      `${baseURL}/collections`,
      {
        name: 'Your Collection Name',
        description: 'Optional description of the collection'
      },
      {
        headers: {
          'x-api-key': apiKey,
          'x-api-secret': apiSecret,
          'Content-Type': 'application/json'
        }
      }
    );
    console.log('Collection created:', response.data);
  } catch (error) {
    console.error('Error creating collection:', error);
  }
}

// Example usage
createCollection();

Python

create-collection.py

import os
import requests

def create_collection():
    # Get API credentials from environment variables
    api_key = os.getenv("FSCO_API_KEY")
    api_secret = os.getenv("FSCO_API_SECRET")

    # Set up headers with API credentials
    headers = {
        "x-api-key": api_key,
        "x-api-secret": api_secret,
        "Content-Type": "application/json"
    }

    # Prepare the request payload
    payload = {
        "name": "Sample Collection",
        "description": "A sample collection for demonstration",
        "type": "DOCUMENT"
    }

    # Make the API request
    response = requests.post(
        "https://api.fsco.io/v2/document/collection",
        json=payload,
        headers=headers
    )

    # Print the response
    print("Collection created:", response.json())

create_collection()

.NET

create-collection.cs

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;

class CollectionCreator
{
    static async Task Main()
    {
        var apiKey = Environment.GetEnvironmentVariable("FSCO_API_KEY");
        var apiSecret = Environment.GetEnvironmentVariable("FSCO_API_SECRET");

        var client = new HttpClient();
        client.DefaultRequestHeaders.Add("x-api-key", apiKey);
        client.DefaultRequestHeaders.Add("x-api-secret", apiSecret);
        client.DefaultRequestHeaders.Add("Content-Type", "application/json");

        var json = "{\"name\": \"Your Collection Name\", \"description\": \"Optional description of the collection\"}";
        var content = new StringContent(json, Encoding.UTF8, "application/json");

        var response = await client.PostAsync("https://api.fsco.io/v2/document/collection", content);
        var responseString = await response.Content.ReadAsStringAsync();

        Console.WriteLine("Collection created: " + responseString);
    }
}

Response

JSON

response.json

{
  "collectionId": "8c1d496f-2827-4750-a11f-74b48c11108d",
  "name": "Your Collection Name",
  "description": "Optional description of the collection",
  "createdAt": "2024-03-20T10:00:00Z",
  "updatedAt": "2024-03-20T10:00:00Z"
}

Update a Collection

Endpoint

PUT /v2/document/collection/{collectionId}

Request Parameters

{
  "name": "Updated Collection Name",
  "description": "Updated description of the collection"
}

The request requires:

• name: The new name for your collection
• description: (Optional) The new description for your collection

Example Request

cURL

update-collection.sh

curl -X PUT https://api.fsco.io/v2/document/collection/8c1d496f-2827-4750-a11f-74b48c11108d \
  -H "x-api-key: $FSCO_API_KEY" \
  -H "x-api-secret: $FSCO_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Collection Name",
    "description": "Updated description of the collection"
  }'

TypeScript

update-collection.ts

import axios from 'axios';

const apiKey = process.env.FSCO_API_KEY;
const apiSecret = process.env.FSCO_API_SECRET;
const baseURL = 'https://api.fsco.com/v2';

async function updateCollection() {
  try {
    const response = await axios.put(
      `${baseURL}/collections/8c1d496f-2827-4750-a11f-74b48c11108d`,
      {
        name: 'Updated Collection Name',
        description: 'Updated description of the collection'
      },
      {
        headers: {
          'x-api-key': apiKey,
          'x-api-secret': apiSecret,
          'Content-Type': 'application/json'
        }
      }
    );
    console.log('Collection updated:', response.data);
  } catch (error) {
    console.error('Error updating collection:', error);
  }
}

// Example usage
updateCollection();

Python

update-collection.py

import os
import requests

api_key = os.getenv('FSCO_API_KEY')
api_secret = os.getenv('FSCO_API_SECRET')
def update_collection():
    collection_id = '8c1d496f-2827-4750-a11f-74b48c11108d'
    url = f'https://api.fsco.io/v2/document/collection/{collection_id}'
    headers = {
        'x-api-key': api_key,
        'x-api-secret': api_secret,
        'Content-Type': 'multipart/form-data'
    }
    data = {
        'name': 'Updated Collection Name',
        'description': 'Updated description of the collection'
    }

    try:
        response = requests.put(url, headers=headers, json=data)
        response.raise_for_status()
        print('Collection updated:', response.json())
    except requests.exceptions.RequestException as e:
        print('Error updating collection:', e)

# Example usage
update_collection()

.NET

update-collection.cs

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;

class CollectionUpdater
{
    static async Task Main()
    {
        var apiKey = Environment.GetEnvironmentVariable("FSCO_API_KEY");
        var apiSecret = Environment.GetEnvironmentVariable("FSCO_API_SECRET");

        var client = new HttpClient();
        client.DefaultRequestHeaders.Add("x-api-key", apiKey);
        client.DefaultRequestHeaders.Add("x-api-secret", apiSecret);
        client.DefaultRequestHeaders.Add("Content-Type", "application/json");

        var collectionId = "8c1d496f-2827-4750-a11f-74b48c11108d";

        var json = "{\"name\": \"Updated Collection Name\", \"description\": \"Updated description of the collection\"}";
        var content = new StringContent(json, Encoding.UTF8, "application/json");

        var response = await client.PutAsync($"https://api.fsco.io/v2/document/collection/{collectionId}", content);
        var responseString = await response.Content.ReadAsStringAsync();

        Console.WriteLine("Collection updated: " + responseString);
    }
}

Response

JSON

response.json

{
  "collectionId": "8c1d496f-2827-4750-a11f-74b48c11108d",
  "name": "Updated Collection Name",
  "description": "Updated description of the collection",
  "createdAt": "2024-03-20T10:00:00Z",
  "updatedAt": "2024-03-20T11:00:00Z"
}

Important Notes

• Store the collectionId securely - you’ll need it for all future collection operations
• Collection names must be unique within your organization
• Updates to a collection will affect all documents within that collection
• You can update either the name, description, or both in a single request

Next Steps

• List Documents
• Manage Templates
• Document Module Overview
• Document API Reference