Position Green Carbon API Integration Guide

A guide to connecting your data systems with Position Green Carbon.

How this Integration Works

To send data to Position Green Carbon, your system will follow a standard 5-step process. Whether you are building a custom connector or running a script manually, this is the process:

1. Authentication: Use your credentials to get a temporary digital key (Access Token).

2. Identification: Ask the system which companies you are allowed to access.

3. Upload: Send the specific file, tagging it with the correct year and accounting standard.

4. Verification: Save the "Upload ID" receipt you get back.

5. Review: Use that receipt to check the logs and ensure the data was processed correctly.

1. Authentication Setup

Before you begin, you need your permanent keys.

Each client is issued two specific credentials. Think of these like a username and password for your software:

• Base URL

• Client ID

• Client Secret

Don't have these? Please request them by emailing support@positiongreen.com

2. Obtain Your Digital Key (Access Token)

You cannot use your ID and Secret to upload files directly. Instead, you exchange them for a temporary "Access Token" valid for 1 hour.

The Action:

Send a POST request to: 

https://<base_url>/auth/client-token

Required Information (Form Data):

• grant_type: Set this exactly to "client_credentials"

• client_id: Your specific Client ID.

• client_secret: Your specific Client Secret.

Success Response:

You will receive a token that looks like a long string of random characters.

JSON

{
    "access_token": "abc12345-random-string...",
    "token_type": "bearer",
    "expires_in": 3600
}

⚠️ Crucial: You must include this access_token in the "Authorization" header for all future steps.

3. Retrieve Authorized Companies

Find out where you are allowed to send data.

The Action:

Send a GET request to: 

https://<base_url>/client/authorized-companies

Required Header:

• Authorization: Bearer {access_token} (Insert the token from Step 2)

Success Response:

You will see a list of companies. You need to copy the external_company_id for the specific company you want to update.

JSON

[
{
        "external_company_id": "comp_998877",
        "name": "Acme Corp"
}
]

4. Uploading Your Data

Send the file to Position Green.

The Action:

Send a POST request to: 

https://<base_url>/client/upload

To ensure your file is processed correctly, you must provide the following three categories of information.

A. Identification (Headers)

These settings tell the system who you are and where the file should go.

• Authorization: Bearer {access_token}

• What it is: The digital key from Step 2.

• company-external-id: {company-external-id}

• What it is: The ID for the company (found in Step 3).

• filename: "{quoted filename}"

• What it is: The exact name of the file you are sending.

• Critical: You must enclose the filename in quotes (e.g., "financials_2023.csv").

B. Accounting Rules (Query Parameters)

These settings tell the system how to read the numbers in your file.

1. Tax Setting (is_vat_included)

• Set to true: If your monetary values include VAT.

• Set to false: If your monetary values exclude VAT.

2. Accounting Standard (account_standard)

• Options: IFRS, NGAP, or OTHER.

• Usage: If you are unsure or want to use the company's default standard, choose OTHER.

3. Reporting Year (year)

• Format: Integer (e.g., 2025)

• Usage: Every row of data inside the file will be assigned to this specific year.

C. The File (Body)

• file: Attach the actual file document here. The file should have the following format, using the following guidelines

Success Response:

If successful, you will receive a receipt. Save this ID.

JSON

{
  "upload_identifier": "12345-abcde-67890"
}

5. Check Processing Logs

Verify that your data was actually read correctly.

The Action:

Send a GET request to: 

https://<base_url>/client/upload/{upload_identifier}/logs

Required Header:

• Authorization: Bearer {access_token}

Success Response:

The system will return a log status, telling you if the data was imported or if errors occurred.

6. Python Usage Example

A ready-to-use script for developers.

import httpx
from urllib.parse import quote
import time

# ==========================================
# ? INPUT REQUIRED: FILL IN THESE VARIABLES
# ==========================================

# 1. Your Credentials (from Step 1)
CLIENT_ID = 'your_client_id_here'
CLIENT_SECRET = 'your_client_secret_here'

# 2. File Details (from Step 4)
FILENAME = 'my_data_2025.csv'      # The name of the file on your computer
YEAR = 2025                        # The year this data belongs to
VAT_INCLUDED = 'true'              # 'true' or 'false'
ACCOUNT_STD = 'NGAP'              # 'IFRS', 'NGAP', or 'OTHER'

# 3. Target Company (Found by running get_authorized_companies)
COMPANY_ID = 'target_company_id_here' 

# ==========================================
# ⚙️ SYSTEM CODE (DO NOT EDIT BELOW)
# ==========================================

URL = 'https://api.morescope.com'

def get_token(base_url):
    """Exchanges credentials for a temporary access token."""
    print('Authenticating...')
    auth_url = f'{base_url}/auth/client-token'
data = {
        'grant_type': 'client_credentials',
        'client_id': CLIENT_ID,
        'client_secret': CLIENT_SECRET
}
    with httpx.Client(timeout=30.0) as client:
r = client.post(auth_url, data=data)
        return r.json()['access_token']

def upload_file(base_url, token, company_id, filename):
    """Uploads the file with the required accounting tags."""
    print(f'Uploading {filename}...')
    upload_url = f'{base_url}/client/upload'

headers = {
        'Authorization': f'Bearer {token}',
        'filename': quote(filename),     # Safely formats the filename
        'company-external-id': company_id,
}

params = {
        'is_vat_included': VAT_INCLUDED,
        'account_standard': ACCOUNT_STD,
        'year': YEAR,
}

    with httpx.Client(timeout=300.0) as client:
        with open(filename, 'rb') as f:
            files = {'file': f}
start = time.time()
r = client.post(upload_url, files=files, headers=headers, params=params)
end = time.time()

            print(f'Upload finished in {end - start:.2f}s')
            print(f'Status: {r.status_code}')
            return r.json()['upload_identifier']

# --- EXECUTION ---
if __name__ == '__main__':
    try:
        # Step 1: Get Token
my_token = get_token(URL)

        # Step 2: Upload File
upload_id = upload_file(URL, my_token, COMPANY_ID, FILENAME)

        print(f"SUCCESS! Save this receipt ID: {upload_id}")

    except Exception as e:
        print(f"An error occurred: {e}")