Introduction
Example requests and responses will appear in this panel. You can select the response format with the tabs above.
The EBU API is a RESTful API for communicating with the English Bridge Union website. It can be used by members, clubs and counties and is the backbone to the My EBU members area.
This document is intended for developers only; we would not recommend that members fiddle with these API calls. There is very little that you can do with the API that you cannot do in My EBU.
Developers are assumed to have some knowledge of how to make HTTPS calls in whatever language they are using. If not, there are far better internet resources to explain this than a bridge union website!
Authentication
Most API calls require authentication to use, for obvious reasons. This is done with either a username/password or a username/token. To add a username/password to your API request you must use the Basic Authentication header. This does make the new API harder to test in a web browser, which is why we recommend the Postman Chrome extension, which makes it very simple to set up and submit HTTP requests.
We have prepared a brief YouTube Video covering how to use Postman.
Tokens
If you submit the parameter reqtoken=1 to the login request a 72-character token will be generated and returned. In future requests (until the token expires) you can use this instead of a password, by submitting a blank password and adding the token to the token parameter.
This is useful to store as a cookie in a website if you (quite rightly) do not want to store the password in plain text during the session. In future we might extend this so that members can generate tokens for third parties without the third party ever having to have the password. Please let us know if this is something that would interest you.
Using a token
Once you have a token you can use this instead of a password. Set the password to blank, and add the token as a URL parameter. e.g.
GET https://www.ebu.co.uk/members/api-3.1/sessions?token=123456789etc
Note that you still need to send the Basic Authentication header, but it will only have the user name and no password.
A note on counties
Throughout this document you will notice that you can only log in as a member, a club or a county. For the purposes of My EBU and the API, organisations which are neither a club nor a county are largely treated as a county. This includes districts, holiday companies and foreign clubs. A few operations are restricted only to genuine counties, but in most ways these other organisations interact with the API in the same way as counties do.
A note on club scorers
It is possible to identify a member of a club as being a designated scorer. This gives them access to some API functions that members normally wouldn’t have, usually involving submission of session results. For the most part, their access will be the same as for a club or county when using these functions, but we will attempt to identify the situations where it differs.
Response format
You can specify the format of the response by setting the Accept header to one of the following values:
- application/json - This is the default if you request anything weird or don’t request anything. Note that some update procedures require you to send back the same JSON-formatted data as the system sends out, so if you are writing anything complex you will find it much easier to use this method.
- application/xml
- text/csv - Can be more human-readable than the above, so is sometimes useful for testing. This is not recommended for production sites as the field layout may be unpredictable and we cannot guarantee that we won’t add extra fields. In particular, certain deeply-nested responses (see
GET /detailsbelow) will simply not work. We make no apologies for this!
You can find examples of all three responses throughout this document in the panel to the right. Click on the tabs at the top to switch to the one you’re most interested in.
Field formats
EBU numbers
EBU membership numbers are always zero-padded to be 8 digits in length. e.g. 00987654 and not 987654.
The exception to this is county membership ‘numbers’ which are always three capital letters. e.g. DEV or SUR.
Dates and times
These are usually returned as a 14-digit number in the format yyyymmddhhiiss. e.g. 20160910184000 would be 6.40pm on September 10th 2016.
Where only the date is used and time is unimportant (date of birth, for example) the time is set to midday. e.g. 20160910120000.
Booleans
True and false values are represented as '1’ and '0’ respectively.
Testing
Hello World
This is a trivial resource just used to test that your application is working, able to send a request to our server and get a response back.
HTTP request
GET https://www.ebu.co.uk/members/api-3.1/hello
{
"response": {
"Hello": "World",
"process_time": "0.0506s"
}
}
<response>
<Hello>World</Hello>
<process_time>0.0396s</process_time>
</response>
response
Hello,World
process_time,0.0585s
GET https://www.ebu.co.uk/members/api-3.1/hello/Suzy
{
"response": {
"Hello": "Suzy",
"process_time": "0.0404s"
}
}
<response>
<Hello>Suzy</Hello>
<process_time>0.0403s</process_time>
</response>
response
Hello,Suzy
process_time,0.0484s
GET https://www.ebu.co.uk/members/api-3.1/hello
GET https://www.ebu.co.uk/members/api-3.1/hello/{name}
Query parameters
| Parameter | Default | Description |
|---|---|---|
| name | World | The name of the person you want to say hello to. |
Login
Performs a login using the EBU number and password of the record. This is only really useful for an interactive website that is requesting a token (see above), since this does nothing else.
If you submit the parameter reqtoken=1 it will return a token to use in future requests (see above).
HTTP request
GET https://www.ebu.co.uk/members/api-3.1/login?reqtoken=1
{
"response": {
"login": "member",
"token": "f55nLWBpytUbjf...",
"process_time": "0.1016s"
}
}
<response>
<login>member</login>
<token>f55nLWBpytUbjf...</token>
<process_time>0.1166s</process_time>
</response>
response
login,member
token,f55nLWBpytUbjf...
process_time,0.1148s
GET https://www.ebu.co.uk/members/api-3.1/login
URL parameters
| Parameter | Description |
|---|---|
| reqtoken | Set to 1 to get the API to return an authentication token |
Response
| Field | Description |
|---|---|
| login | The type of login: 'member’, 'club’ or 'county’. Some functions behave differently depending on what sort of record is authenticating. |
| token | If requested, a token is returned which can be used instead of a password in future requests. |
| process_time | How long our server took to process this request. If you are debugging a slow response, you can compare this to your own response time to see how much time is spent processing the request and how much time is taken up with internet communication. |
login and process_time appear in almost every API response and won’t be noted every time below.
Record details
The details endpoint gets information about the record logging in. It will give slightly different information if you are providing member credentials than if you use club or county credentials.
Get member details
Performing a GET request with member credentials will return data about the member, and about their club memberships.
HTTP Request
GET https://www.ebu.co.uk/members/api-3.1/details
{
"response": {
"login": "member",
"Details": {
"EBU": "00987654",
"Surname": "Bonzo",
"Forenames": "Alfonso",
"Email": "michael@ebu.co.uk",
"Title": "Mr",
"Address": "Unit 4 Broadfields\nBicester Road",
"Town": "Aylesbury",
"County": "Buckinghamshire",
"Country": "United Kingdom",
"Postcode": "HP19 8AZ",
"RegionCode": "OXF",
"RegionName": "Oxfordshire",
"Tel1": "01296 317200",
"Tel2": "01296 317207",
"DOB": "19300110120000",
"Anonymous": "0",
"MagazinePreference": "Only Diary Edition",
"NGSPreference": "Public Grade and Partnerships",
"AppearInMagazine": "0",
"ReceiveMassEmails": "1",
"ReceiveMassEmailsEBED": "1"
},
"Clubs": {
"Primary": [
{
"EBU": "00431222",
"ID": 772147,
"Name": "Test Club",
"Permission": "00"
}
],
"Secondary": [],
"All": [
{
"EBU": "00431222",
"ID": 772147,
"Name": "Test Club",
"Permission": "00"
}
]
},
"process_time": "3.2187s"
}
}
<response>
<login>member</login>
<Details>
<EBU>00987654</EBU>
<Surname>Bonzo</Surname>
<Forenames>Alfonso</Forenames>
<Email>michael@ebu.co.uk</Email>
<Title>Mr</Title>
<Address>Unit 4 Broadfields
Bicester Road</Address>
<Town>Aylesbury</Town>
<County>Buckinghamshire</County>
<Country>United Kingdom</Country>
<Postcode>HP19 8AZ</Postcode>
<RegionCode>OXF</RegionCode>
<RegionName>Oxfordshire</RegionName>
<Tel1>01296 317200</Tel1>
<Tel2>01296 317207</Tel2>
<DOB>19300110120000</DOB>
<Anonymous>0</Anonymous>
<MagazinePreference>Only Diary Edition</MagazinePreference>
<NGSPreference>Public Grade and Partnerships</NGSPreference>
<AppearInMagazine>0</AppearInMagazine>
<ReceiveMassEmails>1</ReceiveMassEmails>
<ReceiveMassEmailsEBED>1</ReceiveMassEmails>
</Details>
<Clubs>
<Primary>
<ListItem>
<EBU>00987650</EBU>
<ID>999999</ID>
<Name>Test Club</Name>
<Permission>00</Permission>
</ListItem>
</Primary>
<Secondary></Secondary>
<All>
<ListItem>
<EBU>00987650</EBU>
<ID>999999</ID>
<Name>Test Club</Name>
<Permission>00</Permission>
</ListItem>
</All>
</Clubs>
<process_time>3.1248s</process_time>
</response>
response
login,member
Details,00987654,Bonzo,Alfonso,michael@ebu.co.uk,Mr,Unit 4 Broadfields\nBicester Road,Aylesbury,Buckinghamshire,United Kingdom,HP19 8AZ,OXF,Oxfordshire,01296 317200,01296 317207,19300110120000,0,Only Diary Edition,0,0,1
Clubs,Array,Array
process_time,3.5581s
Note that this is one of the API calls which really does not work very well with a CSV response.
GET https://www.ebu.co.uk/members/api-3.1/details
Details Response
The following fields are returned in the Details section of the response.
| Field | Description |
|---|---|
| EBU | The member’s EBU number. |
| Surname | The member’s surname (family name). |
| Forenames | The member’s forenames (can be more than one). |
| The member’s email address. | |
| Title | The member’s title e.g. Mr, Miss, Dr. |
| Address | The street address. May contain newlines or \n characters to separate lines. |
| Town | The address town. |
| County | The address county. Note: not the county of affiliation. |
| Country | The address country. |
| Postcode | The address postcode. Foreign country equivalents also go here. |
| RegionCode | The three-letter code of the county of primary affiliation. |
| RegionName | The name of the county of primary affiliation. |
| Tel1, Tel2 | The member’s telephone number(s). |
| DOB | The date of birth. |
| Anonymous | Boolean to show whether the member has chosen to remain anonymous to the EBU. |
| MagazinePreference | Which paper magazines they have chosen to receive (if eligible). Can take the values ‘All Editions + Diary’, 'All Editions, No Diary’, 'Only Diary Edition’ and 'No Editions’. Be careful with this one when changing it, since you will need to URL encode the + sign or it won’t be recognised as a valid value. |
| NGSPreference | Whether the member has chosen to keep their NGS details private. Can be set to “Public Grade and Partnerships”, “Private Grade and Partnerships” or “Public Grade, Private Partnerships”. |
| AppearInMagazine | Whether the member wishes to appear in the magazine when they earn a landmark masterpoint promotion. |
| ReceiveMassEmails | Whether the member wishes to opt out of mass emails sent by the EBU e.g. newsletters and magazine notifications. |
| ReceiveMassEmailsEBED | Whether the member wishes to opt out EBED-related mass emails sent by the EBU e.g. newsletters. |
Clubs Response
The Clubs section of the response is broken down into Primary, Secondary and All lists. Primary lists the one primary club which the member belongs to. Secondary lists all of the other clubs the member belongs to. And All merges both lists together so that you don’t have to. Each club entry returns the following fields:
| Field | Description |
|---|---|
| EBU | The EBU number of the club. |
| ID | An internal identifier. Has no use except you need to send this back if changing the club settings with the POST /details API call. See below. |
| Name | The club’s name. |
| Permission | A two-bit field containing the read and write permission that the club has over the member’s record, in that order. The left bit set to 1 means that the club has access to the member’s full details. The right bit set to 1 means that the club can edit the member’s details on their behalf. |
Update member details
A POST request to the same endpoint will update membership details.
HTTP Request
POST https://www.ebu.co.uk/members/api-3.1/details?data={"Details": {"Forenames": "Martin"}}
{
"response": {
"login": "member",
"Messages": [
"Updating Forenames with value 'Martin' (was Harold)"
],
"process_time": "1.5888s"
}
}
<response>
<login>member</login>
<Messages>Updating Forenames with value 'Martin' (was Harold)</Messages>
<process_time>1.5888s</process_time>
</response>
response
login,member
Messages,Updating Forenames with value 'Martin' (was Harold)
process_time,1.5888s
POST https://www.ebu.co.uk/members/api-3.1/details
This procedure call expects a JSON string to be sent in the data URL parameter. The format of this JSON string is identical to the corresponding GET /details JSON response above (everything below the 'response’). You can build this up yourself for simple changes, but if there’s a lot to change you will find it substantially simpler to take a copy of the response from the GET, amend it appropriately, and send it back via the POST.
Not all fields are editable by a member. In particular, RegionCode and RegionName can only be changed by application to the EBU office. DOB can also not be changed directly. Club permissions can be changed, and a different Primary Club selected, but you cannot join a new club, or resign from an old club - the club officials will need to do this.
Fields can be omitted. Their value will not be amended or deleted.
Response
| Field | Description |
|---|---|
| Messages | A list of messages giving some narrative about what has happened. |
Clubs section
To change a club permission you need to supply the ID and EBU fields exactly as they are in the GET response, above. (Yes, forcing you to supply the ID is a little ugly but this is the easiest way to speed up the response.)
Note that the data in the Primary and Secondary sections is duplicated in the All section. It’s best to keep things consistent between them, as what gets written to the database may act unpredictably otherwise.
Get club/county details
Performing a GET request with club credentials is currently far less informative than for a member. You only get the club name, but this may be extended in future.
County logins work identically to club logins for this endpoint.
HTTP Request
GET https://www.ebu.co.uk/members/api-3.1/details
{
"response": {
"login": "club",
"Name": "Test Club",
"process_time": "0.5151s"
}
}
<response>
<login>club</login>
<Name>Test Club</Name>
<process_time>0.5151s</process_time>
</response>
response
login,club
Name,Test Club
process_time,0.5151s
GET https://www.ebu.co.uk/members/api-3.1/details
Response
| Field | Description |
|---|---|
| Name | The club/county name. |
Update club/county details
There is no POST equivalent for clubs or counties to update their details via the API. This may happen in future, but for now requests for changes should be sent to Kay Carter at the EBU office.
Session details
The session endpoint gets information about the sessions of the record logging in. For a member, it will return the sessions they participated in. For a club or county, it will be the sessions they ran.
Note that we use session in all of these calls and not the plural sessions. In this case we favour consistency of naming over good English.
Get list of a member’s sessions
Performing a GET request with member credentials will return a list of sessions which that member played.
HTTP Request
GET https://www.ebu.co.uk/members/api-3.1/session
{
"response": {
"login": "member",
"Session": [
{
"ID": "EBU-003621-0031",
"SID": "EBU-003621",
"Date": "20170101120000",
"Score": "",
"VPScore": "43",
"Partner": [
{
"EBU": "00987654",
"Name": "Edith Hubbard"
}
],
"MPs": "0",
"GMPs": "0",
"BMPs": "0",
"Club": "EBU",
"ClubName": "English Bridge Union",
"NGS": [
{
"SOpp": "60.51",
"Partner": "00987654",
"PartnerName": "Edith Hubbard",
"PrevGrade": "59.29",
"NewGrade": "60.29",
"SessionGrade": "71.67",
"GradeAdj": "6.19",
"Boards": "24",
"Score": "56.55",
"Order": "",
"SeqNum": "00447104",
"Format": "SWISS_PAIRS"
}
]
}
],
"process_time": "4.1651s"
}
}
<response>
<login>member</login>
<Session></Session>
<Session>
<ID>EBU-003621-0031</ID>
<SID>EBU-003621</SID>
<Date>20170101120000</Date>
<Score></Score>
<VPScore>43</VPScore>
<Partner>
<ListItem>
<EBU>00987654</EBU>
<Name>Edith Hubbard</Name>
</ListItem>
</Partner>
<MPs>0</MPs>
<GMPs>0</GMPs>
<BMPs>0</BMPs>
<Club>EBU</Club>
<ClubName>English Bridge Union</ClubName>
<NGS>
<ListItem>
<SOpp>60.51</SOpp>
<Partner>00987654</Partner>
<PartnerName>Edith Hubbard</PartnerName>
<PrevGrade>59.29</PrevGrade>
<NewGrade>60.29</NewGrade>
<SessionGrade>71.67</SessionGrade>
<GradeAdj>6.19</GradeAdj>
<Boards>24</Boards>
<Score>56.55</Score>
<Order></Order>
<SeqNum>00447104</SeqNum>
<Format>SWISS_PAIRS</Format>
</ListItem>
</NGS>
</Session>
<process_time>4.1651s</process_time>
</response>
response
login,member
Session,EBU-003621-0031,EBU-003621,20170101120000,,43,Array,0,0,0,EBU,English Bridge Union,Array
process_time,4.1651s
GET https://www.ebu.co.uk/members/api-3.1/session
Query parameters
| Parameter | Default | Description |
|---|---|---|
| from | 20100401 | The start of the period you want to retrieve in format ‘yyyymmdd’. You can use the special values 'thisyear’ and 'lastyear’ to choose 1st January of the respective year. |
| to | today | The end of the period you want to retrieve in format 'yyyymmdd’. You can use the special values 'thisyear’ and 'lastyear’ to choose 31st December of the respective year. |
Response
The response comes back as a list of Session objects, each containing the following fields.
| Field | Description |
|---|---|
| ID | A unique ID for that player’s session of bridge. This will always begin with the SID (below). |
| SID | The ID of the session. |
| Date | The date of the session. |
| Score | What the player scored in the session, if available. |
| VPScore | The Victory Point score, if there is one. |
| Partner | A list of partners. If a team’s event, a list of teammates. |
| MPs | The local masterpoints earned in this session. |
| BMPs | The blue masterpoints earned in this session. |
| GMPs | The green masterpoints earned in this session. |
| Club | The Club’s EBU number. |
| ClubName | The Club’s name. |
| NGS | Information about the NGS for this session. Appears in list form and will contain multiple entries if we played with multiple partners (e.g. in a pivot teams event). See below for detail. |
| NGS Field | Description |
|---|---|
| SOpp | The strength of the opposition. |
| Partner | The EBU number of the partner. |
| PartnerName | The name of the partner. |
| PrevGrade | The grade prior to this session. |
| NewGrade | The grade after this session. |
| SessionGrade | The session grade (see NGS documentation for exactly what this means, but it’s not especially interesting) |
| GradeAdj | How the grade changed as a result of this session. Can be positive or negative. |
| Boards | How many graded boards this partnership played. |
| Score | The score which the NGS used for this partnership. |
| Order | Used when someone has multiple partners to give a unique ID to this partnership. Blank otherwise. |
| SeqNum | The sequence number for when the NGS system processed this session. Can be used to put in order sessions which might not have been submitted in date order. |
| Format | The format of the event. |
Get list of a club/county’s sessions
Performing a GET request with club or county credentials will return a list of sessions which that club/county held.
HTTP Request
GET https://www.ebu.co.uk/members/api-3.1/session
{
"response": {
"login": "county",
"Session": [
{
"ID": "EBU-004255",
"Date": "20170101120000",
"DateSubmitted": "20170101142142",
"Description": "Test Event 1",
"PlayerSessions": "72",
"Format": "TEAMS",
"Invoice": "0",
"MPScale": "EBU",
"P2PChargeRate": "02",
"MPUploaded": "0",
"MPAwarded": "1",
"NGSReprocessing": "0",
"NGS": "done",
"SOF": "58.87",
"IsIndex": "1",
"SessionWeight": "1",
"WinnerType": "1"
},
{
"ID": "EBU-004256",
"Date": "20170101120000",
"DateSubmitted": "20170101142142",
"Description": "Test Event 2",
"PlayerSessions": "72",
"Format": "TEAMS",
"Invoice": "0",
"MPScale": "EBU",
"P2PChargeRate": "20",
"MPUploaded": "0",
"MPAwarded": "1",
"NGSReprocessing": "0",
"NGS": "multiSibling",
"Index": "EBU-004255",
"SessionWeight": "1",
"WinnerType": "1"
}
],
"process_time": "3.1648s"
}
}
<response>
<login>county</login>
<Session>
<ID>EBU-004255</ID>
<Date>20170101120000</Date>
<DateSubmitted>20170101142142</DateSubmitted>
<Description>Test Event 1</Description>
<PlayerSessions>72</PlayerSessions>
<Format>TEAMS</Format>
<Invoice>0</Invoice>
<MPScale>EBU</MPScale>
<P2PChargeRate>02</P2PChargeRate>
<MPUploaded>0</MPUploaded>
<MPAwarded>1</MPAwarded>
<NGSReprocessing>0</NGSReprocessing>
<NGS>done</NGS>
<SOF>58.87</SOF>
<IsIndex>1</IsIndex>
<SessionWeight>1</SessionWeight>
<WinnerType>1</WinnerType>
</Session>
<Session>
<ID>EBU-004256</ID>
<Date>20170101120000</Date>
<DateSubmitted>20170101142142</DateSubmitted>
<Description>Test Event 2</Description>
<PlayerSessions>72</PlayerSessions>
<Format>TEAMS</Format>
<Invoice>0</Invoice>
<MPScale>EBU</MPScale>
<P2PChargeRate>99</P2PChargeRate>
<MPUploaded>0</MPUploaded>
<MPAwarded>1</MPAwarded>
<NGSReprocessing>0</NGSReprocessing>
<NGS>multiSibling</NGS>
<Index>EBU-004255</Index>
<SessionWeight>1</SessionWeight>
<WinnerType>1</WinnerType>
</Session>
<process_time>3.1648s</process_time>
</response>
response
login,county
Session,EBU-004255,20170101120000,20170101142142,Test Event 1,72,TEAMS,0,EBU,02,0,1,0,done,58.87,1,1,1
Session,EBU-004256,20170101120000,20170101142142,Test Event 2,72,TEAMS,0,EBU,99,0,1,0,multiSibling,EBU-004255,1,1
process_time,3.1648s
GET https://www.ebu.co.uk/members/api-3.1/session
Query parameters
| Parameter | Default | Description |
|---|---|---|
| from | 20100401 | The start of the period you want to retrieve in format 'yyyymmdd’. You can use the special values 'thisyear’ and 'lastyear’ to choose 1st January of the respective year. |
| to | today | The end of the period you want to retrieve in format 'yyyymmdd’. You can use the special values 'thisyear’ and 'lastyear’ to choose 31st December of the respective year. |
Response
The response comes back as a list of Session objects, each containing the following fields.
| Field | Description |
|---|---|
| ID | The ID of the session. |
| Date | The date the session was played. |
| DateSubmitted | The date/time the session was submitted. |
| Description | What the session was named. |
| PlayerSessions | How many people played in the session. |
| Format | What the format of the session was. |
| Invoice | Once an invoice or collection advice has been created for this session, this field will contain a reference to it. Until then, it will take the value '0’. See Statements and invoices in the Club admin section below. |
| MPScale | The masterpoint scale of the session. |
| P2PChargeRate | Now usually called the Universal Membership Subscription Rate, this tells the EBU what kind of an event it was, and therefore what to charge the club/county. |
| MPUploaded | Boolean for whether masterpoints have been processed for this session or not. |
| MPAwarded | Whether the session is eligible for masterpoints. Not really used for anything. |
| NGSReprocessing | Set to '1’ if the session is due to be reprocessed by the NGS system on the next morning. This usually means that the P2PChargeRate has changed, but there could be a few other reasons. |
| NGS | The status of the event. Will say 'done’ if the session was successfully processed by the NGS, or give some other message if not. |
| SOF | The strength of the field, for the NGS. |
| IsIndex | A boolean to say if this is the index session for a multi-session submission. |
| Index | The session ID of the index of this multi-session submission. |
| SessionWeight | How many real life sessions this session represents. Should be set to 2 for events with 36+ boards. |
| SimPairsID | If the session has been submitted to a Sim Pairs event, the ID will be noted here. |
| WinnerType | Whether it was a one- or two-winner movement. |
Get session summary for a club/county
This endpoint gets a brief summary of a club or county’s session history.
HTTP Request
GET https://www.ebu.co.uk/members/api-3.1/session/summary
{
"response": {
"login": "county",
"count": 3221,
"first": "20101105120000",
"Session": [
{
"Placeholder": "Session 1 data"
},
{
"Placeholder": "Session 2 data"
},
{
"Placeholder": "Session 3 data"
},
{
"Placeholder": "Session 4 data"
},
{
"Placeholder": "Session 5 data"
}
],
"process_time": "1.4009s"
}
}
<response>
<login>county</login>
<count>3221</count>
<first>20101105120000</first>
<Session>
<Placeholder>Session 1 data</Placeholder>
</Session>
<Session>
<Placeholder>Session 2 data</Placeholder>
</Session>
<Session>
<Placeholder>Session 3 data</Placeholder>
</Session>
<Session>
<Placeholder>Session 4 data</Placeholder>
</Session>
<Session>
<Placeholder>Session 5 data</Placeholder>
</Session>
<process_time>1.4009s</process_time>
</response>
response
login,county
count,3221
first,20101105120000
Session,1
Session,2
Session,3
Session,4
Session,5
process_time,1.4009s
GET https://www.ebu.co.uk/members/api-3.1/session/summary
Response
| Field | Description |
|---|---|
| count | The number of sessions that have been submitted by this club/county |
| first | The date of the earliest session submitted |
| Session | A list of the five most recent sessions that the club/county has played. The format of these is the same as for the GET /session query and has not been duplicated in the example to the right. |
Get ranking list for a specific session
This endpoint retrieves the ranking list for a specific session. To get the ID of a session, you need to use one of the above calls.
HTTP Request
GET https://www.ebu.co.uk/members/api-3.1/session/EBU-004255
{
"response": {
"login": "county",
"Session": [
{
"ID": "EBU-004255",
"Date": "20170101120000",
"DateSubmitted": "20170101142142",
"Description": "Test Event 1",
"PlayerSessions": "72",
"Format": "TEAMS",
"Invoice": "0",
"MPScale": "EBU",
"P2PChargeRate": "02",
"MPUploaded": "0",
"MPAwarded": "1",
"NGSReprocessing": "0",
"NGS": "done",
"SOF": "58.87",
"IsIndex": "1",
"SessionWeight": "1",
"WinnerType": "1"
}
],
"Player": [
{
"ID": "EBU-004255-0001",
"EBU": "00987654",
"Partner": "00987653",
"Place": "6",
"Name": "Bobby McBob",
"Score": "58.00",
"MPs": "0",
"GMPs": "0",
"BMPs": "192",
"Pair": "1",
"NGS": [
{
"Adjust": "5.30",
"Score": "58.00",
"Boards": "24"
}
]
},
{
etc.
}
],
"SimsRegistered": [
{
"ID": "000001",
"Description": "Test Sim Pairs"
}
],
"process_time": "1.2109s"
}
}
<response>
<login>county</login>
<Session>
<ID>EBU-004255</ID>
<Date>20170101120000</Date>
<DateSubmitted>20170101142142</DateSubmitted>
<Description>Test Event 1</Description>
<PlayerSessions>72</PlayerSessions>
<Format>TEAMS</Format>
<Invoice>0</Invoice>
<MPScale>EBU</MPScale>
<P2PChargeRate>02</P2PChargeRate>
<MPUploaded>0</MPUploaded>
<MPAwarded>1</MPAwarded>
<NGSReprocessing>0</NGSReprocessing>
<NGS>done</NGS>
<SOF>58.87</SOF>
<IsIndex>1</IsIndex>
<SessionWeight>1</SessionWeight>
<WinnerType>1</WinnerType>
</Session>
<Player>
<ID>EBU-004255-0001</ID>
<EBU>00987654</EBU>
<Partner>00987653</Partner>
<Place>6</Place>
<Name>Bobby McBob</Name>
<Score>58.00</Score>
<MPs>0</MPs>
<GMPs>0</GMPs>
<BMPs>192</BMPs>
<Pair>1</Pair>
<NGS>
<ListItem>
<Adjust>5.30</Adjust>
<Score>58.00</Score>
<Boards>24</Boards>
</ListItem>
</NGS>
</Player>
<Player>
etc.
</Player>
<SimsRegistered>
<ID>000001</ID>
<Description>Test Sim Pairs</Description>
</SimsRegistered>
<process_time>1.0747s</process_time>
</response>
response
login,county
Session,EBU-004255,20170101120000,20170101142142,Test Event 1,72,TEAMS,0,EBU,02,0,1,0,done,58.87,1,1,1
Player,EBU-004255-0001,00987654,00987653,6,Bobby McBob,58.00,0,0,192,1,Array
Player,etc.
SimsRegistered,000001,Test Sim Pairs
process_time,1.2294s
GET https://www.ebu.co.uk/members/api-3.1/session/{id}
Response
The examples to the right and information below refer to retrieving this data as a club/county. However, the response is very similar if you’re doing this as a member. Members can only access information about sessions in which they participated.
| Field | Description |
|---|---|
| Session | This field duplicates the information that would be returned by the GET session list. See above for detail. The rest of this table lists the detail of the Player elements. |
| ID | The ranking ID. This will always start with the session ID, followed by a unique reference for this player’s data. |
| EBU | The EBU number of the player. |
| Partner | The EBU number of the player’s partner. |
| Place | The position that the pair/team came. |
| Name | The name of the player. |
| Score | The score of the pair/team. |
| MPs | The local masterpoints earned. |
| GMPs | The green masterpoints earned. |
| BMPs | The blue masterpoints earned. |
| Pair | The pair ID. |
| NGS | A list of NGS adjustments (along with score and number of boards played) by partnership. Will usually contain just one item, but may contain more in the case of a player playing in multiple partnerships. e.g. Pivot teams. |
| SimsRegistered | Lists the sim pairs events that this club is registered for on this day. Note that this does not mean that the session has been entered into the Sim. That information can be found in the Session section. |
Get a player’s session history as a club/county
This endpoint lets a club or county retrieve some very basic information about a player’s session history. This can be useful for disambiguating player records with similar names.
HTTP Request
GET https://www.ebu.co.uk/members/api-3.1/session/player/00987654
{
"response": {
"login": "county",
"Session": [
{
"ID": "EBU-004255",
"Date": "20160819120000",
"Club": "EBU",
"ClubName": "English Bridge Union"
},
{
etc.
}
],
"process_time": "1.2119s"
}
}
<response>
<login>county</login>
<Session>
<ID>EBU-004255</ID>
<Date>20160819120000</Date>
<Club>EBU</Club>
<ClubName>English Bridge Union</ClubName>
</Session>
<Session>
etc.
</Session>
<process_time>1.3376s</process_time>
</response>
response
login,county
Session,EBU-004255,20160819120000,EBU,English Bridge Union
process_time,0.8857s
GET https://www.ebu.co.uk/members/api-3.1/session/player/{ebu}
Query parameters
| Parameter | Default | Description |
|---|---|---|
| from | 20100401 | The start of the period you want to retrieve in format 'yyyymmdd’. You can use the special values 'thisyear’ and 'lastyear’ to choose 1st January of the respective year. |
| to | today | The end of the period you want to retrieve in format 'yyyymmdd’. You can use the special values 'thisyear’ and 'lastyear’ to choose 31st December of the respective year. |
Response
Returns a list of Session items with the following fields.
| Field | Description |
|---|---|
| ID | The session ID. |
| Date | The date of the session. |
| Club | The EBU number of the club. |
| ClubName | The name of the club. |
Delete a session
This endpoint lets a club or county delete one of their sessions. This can only be done up to the point where the session has been processed for masterpoints, which happens a week into the month after it was submitted (so clubs will always have at least a week to correct any mistakes). After this, they need to contact the EBU for assistance. To check if masterpoints have been issued, retrieve the Session data and look for the MPUploaded value.
HTTP Request
DELETE https://www.ebu.co.uk/members/api-3.1/session/00987654-000001
{
"response": {
"login": "club",
"deleted": "00987654-000001",
"process_time": "8.6671s"
}
}
<response>
<login>club</login>
<deleted>00987654-000001</deleted>
<process_time>8.6671s</process_time>
</response>
response
login,club
deleted,00987654-000001
process_time,8.6671s
DELETE https://www.ebu.co.uk/members/api-3.1/session/{id}
Response
Returns a failure message, or deleted if successful. Will usually just return one deleted element, but in the case of a multi-session event, there may be several sub-sessions being deleted.
| Field | Description |
|---|---|
| deleted | The session ID of the session deleted. |
Update a session
This endpoint lets a club or county update a player record on one of their sessions. As with deleting, above, this can only be done up to the point where the session has been processed for masterpoints, which happens a week into the month after it was submitted (so clubs will always have at least a week to correct any mistakes). After this, they need to contact the EBU for assistance. To check if masterpoints have been issued, retrieve the Session data and look for the MPUploaded value.
HTTP Request
POST https://www.ebu.co.uk/members/api-3.1/session/ranking/00987654-000001-0001
{
"response": {
"login": "club",
"success": "Doctor Spaceman",
"process_time": "2.9236s"
}
}
<response>
<login>club</login>
<success>Doctor Spaceman</success>
<process_time>2.4958s</process_time>
</response>
response
login,club
success,Doctor Spaceman
process_time,1.7312s
POST https://www.ebu.co.uk/members/api-3.1/session/ranking/{rid}
Query parameters
| Parameter | Default | Description |
|---|---|---|
| ebu | none | The EBU number of the player to change this session to. |
Response
| Field | Description |
|---|---|
| success | The name of the player you’re changing the session to. |
NGS information
These procedure calls deal with the EBU’s National Grading Scheme. This documentation isn’t going to explain the details of how it works. For that, please explore https://www.ebu.co.uk/ngs.
Get member’s NGS details
This endpoint retrieves all the information you could need about a person’s current NGS grade. It requires a member’s EBU number and password to use.
HTTP Request
GET https://www.ebu.co.uk/members/api-3.1/ngs
{
"response": {
"login": "member",
"SumBoards": "0300",
"Grade": "60.00",
"GradeBand": "King ",
"Maturity": "E",
"Partner": [
{
"Data": {
"Name": "Billy Bobbin",
"Grade": "61.07",
"GradeBand": "Ace-C",
"Maturity": "E"
},
"NewestDateUsed": "20150518120000",
"OldestDateUsed": "20141117120000",
"SumBoards": "0300",
"Maturity": "E",
"Grade": "60.50",
"GradeBand": "King "
}
],
"OldestDateUsed": "20141117120000",
"chartdata": [
{
"x": 1,
"y": 49.71,
"toolTipContent": "2010-05-13, grade: 49.71"
},
{
"x": 2,
"y": 48.74,
"toolTipContent": "2010-10-25, grade: 48.74"
},
{
"x": 3,
"y": 49.46,
"toolTipContent": "2011-12-28, grade: 49.46"
}
],
"History": [
{
"NewGrade": "60.00",
"Date": "20170601120000",
"Invalid": "session",
"Session": "EBU-000001",
"Adjust": "5.00",
"SeqNum": "00510000",
"SumBoards": "0300",
"NumBoards": "24"
}
],
"process_time": "1.5801s"
}
}
<response>
<login>member</login>
<SumBoards>0300</SumBoards>
<Grade>60.00</Grade>
<GradeBand>King </GradeBand>
<Maturity>E</Maturity>
<OldestDateUsed>20141117120000</OldestDateUsed>
<Partner>
<Data>
<Name>Billy Bobbin</Name>
<Grade>61.07</Grade>
<GradeBand>Ace-C</GradeBand>
<Maturity>E</Maturity>
</Data>
<NewestDateUsed>20150518120000</NewestDateUsed>
<OldestDateUsed>20141117120000</OldestDateUsed>
<SumBoards>0300</SumBoards>
<Maturity>E</Maturity>
<Grade>60.50</Grade>
<GradeBand>King </GradeBand>
</Partner>
<chartdata>
<ListItem>
<x>1</x>
<y>49.71</y>
<toolTipContent>2010-05-13, grade: 49.71</toolTipContent>
</ListItem>
<ListItem>
<x>2</x>
<y>48.74</y>
<toolTipContent>2010-10-25, grade: 48.74</toolTipContent>
</ListItem>
<ListItem>
<x>3</x>
<y>49.46</y>
<toolTipContent>2011-12-28, grade: 49.46</toolTipContent>
</ListItem>
</chartdata>
<History>
<NewGrade>60.00</NewGrade>
<Date>20170601120000</Date>
<Invalid>session</Invalid>
<Session>EBU-000001</Session>
<Adjust>5.00</Adjust>
<SeqNum>00510000</SeqNum>
<SumBoards>0300</SumBoards>
<NumBoards>24</NumBoards>
</History>
<process_time>2.2668s</process_time>
</response>
response
login,member
SumBoards,0300
Grade,60.00
GradeBand,King
Maturity,E
OldestDateUsed,20141117120000
Partner,Billy Bobbin,61.07,Ace-C,E,20150518120000,20141117120000,0300,E,65.50,King
chartdata,1,49.71,2010-05-13, grade: 49.71,2,48.74,2010-10-25, grade: 48.74,3,49.46,2011-12-28, grade: 49.46
History,60.00,20170601120000,session,EBU-000001,5.00,00510000,0300,24
process_time,1.7692s
GET https://www.ebu.co.uk/members/api-3.1/ngs
Response
| Field | Description |
|---|---|
| SumBoards | The number of boards graded by the NGS. This is capped at 2000 and only looks at the last three years, so is not the same as the number of boards they have ever played. |
| Grade | The NGS grade. |
| GradeBand | The grade band of this grade. |
| Maturity | E = evolving (<1000 boards) and M = mature. |
| Partner | A list of partnerships, with data on the partnership grade. The Data field gives data about the partner - their name and individual grade. |
| OldestDateUsed | The date of the oldest session used in the current grade. |
| chartdata | Data which we use to print the graph on the NGS page of My EBU. |
| History | A list of the 20 most recent NGS movements for that player. This is more accurate than looking at the session history and ordering it by NGS sequence number, because it includes information on when a session is deleted, or recalculated. The not-very-usefully-named Invalid field can take the values ‘session’ (this is a normal graded session), 'deleted-session’ (the grade changed when a session was deleted), 'recalculation’ (the grade changed when a session was recalculated) and 'expiry’ (some sessions were removed because they were more than three years old). |
Look up a member’s NGS by name
This endpoint lets you search for an NGS record by surname (and, optionally, forename). Only EBU members who have a public NGS grade will appear in the results.
HTTP Request
GET https://www.ebu.co.uk/members/api-3.1/ngs/search
{
"response": {
"player": [
{
"Position": 1,
"Surname": "Bobbin",
"Forenames": "Malcolm",
"Grade": "58.52",
"GradeBand": "Queen",
"Maturity": "M",
"Region": "SUR"
},
{
"Position": 2,
"Surname": "Bobbin",
"Forenames": "Mary",
"Grade": "38.08",
"GradeBand": "Two ",
"Maturity": "E",
"Region": "WIL"
}
],
"process_time": "0.1858s"
}
}
<response>
<player>
<Position>1</Position>
<Surname>Bobbin</Surname>
<Forenames>Malcolm</Forenames>
<Grade>58.52</Grade>
<GradeBand>Queen</GradeBand>
<Maturity>M</Maturity>
<Region>SUR</Region>
</player>
<player>
<Position>2</Position>
<Surname>Bobbin</Surname>
<Forenames>Mary</Forenames>
<Grade>38.08</Grade>
<GradeBand>Two </GradeBand>
<Maturity>E</Maturity>
<Region>WIL</Region>
</player>
<process_time>0.1858s</process_time>
</response>
response
player,1,Bobbin,Malcolm,58.52,Queen,M,SUR
player,2,Bobbin,Mary,38.08,Two ,E,WIL
process_time,0.1858s
GET https://www.ebu.co.uk/members/api-3.1/ngs/search
Query parameters
| Parameter | Default | Description |
|---|---|---|
| surname | none | The surname to search for. This needs to be complete, so 'Chan’ will not pick up people called 'Channing’. |
| forenames | none | (Optional) The forenames to search for. This does not need to be complete, so both 'Mal’ and ’M’ will pick up people called 'Malcolm’. |
Response
| Field | Description |
|---|---|
| Position | The position in the list. Probably not very useful, unless you want to find out who the best 'Smith’ in England is. |
| Surname | |
| Forenames | |
| Grade | The grade of the player. |
| GradeBand | The grade band of the player. |
| Maturity | How mature (or reliable) the grade is. 'E’ means it is evolving (150-999 boards); ’M’ means it is mature (1000+ boards). Grades with fewer than 150 boards to support them will not appear. |
| Region | The primary county of this player, as a three-letter code. |
Look up a member’s NGS by EBU number
This endpoint lets you look up an NGS grade by EBU number. Only members who have a public NGS grade can be retrieved.
HTTP Request
GET https://www.ebu.co.uk/members/api-3.1/ngs/00987654
{
"response": {
"Maturity": "E",
"Grade": "60.15",
"GradeBand": "King ",
"process_time": "2.5880s"
}
}
{
"response": {
"failure": "This member has denied permission to view their grade",
"process_time": "0.8739s"
}
}
<response>
<Maturity>E</Maturity>
<Grade>60.15</Grade>
<GradeBand>King </GradeBand>
<process_time>2.5880s</process_time>
</response>
<response>
<failure>This member has denied permission to view their grade</failure>
<process_time>0.8739s</process_time>
</response>
response
Maturity,E
Grade,60.15
GradeBand,King
process_time,2.5880s
response
failure,This member has denied permission to view their grade
process_time,0.8739s
GET https://www.ebu.co.uk/members/api-3.1/ngs/{id}
Response
Responds with a 'failure’ field if the grade information could not be retrieved.
| Field | Description |
|---|---|
| Maturity | How mature (or reliable) the grade is. 'E’ means it is evolving (150-999 boards); ’M’ means it is mature (1000+ boards). Grades with fewer than 150 boards to support them will not appear. |
| Grade | The grade of the player. |
| GradeBand | The grade band of the player. |
Get public NGS ranking list
This endpoint retrieves the public ranking list of all players, starting from the top. You can restrict it by county and grade maturity. It returns results in pages of 50 records.
HTTP Request
GET https://www.ebu.co.uk/members/api-3.1/ngs/ranking
{
"response": {
"player": [
{
"Position": 1,
"Name": "Andrew Robson",
"Grade": "72.60",
"GradeBand": "Ace-S",
"Maturity": "M",
"Region": "LON"
},
{
"Position": 2,
"Name": "David Gold",
"Grade": "70.85",
"GradeBand": "Ace-S",
"Maturity": "M",
"Region": "LON"
},
{
"etc": "..."
},
{
"Position": 49,
"Name": "Steve Eginton",
"Grade": "66.58",
"GradeBand": "Ace-H",
"Maturity": "M",
"Region": "BRB"
},
{
"Position": 50,
"Name": "Martin Jones",
"Grade": "66.57",
"GradeBand": "Ace-H",
"Maturity": "M",
"Region": "MID"
}
],
"shown": "all",
"start": 1,
"end": 50,
"process_time": "0.0701s"
}
}
<response>
<player>
<Position>1</Position>
<Name>Andrew Robson</Name>
<Grade>72.60</Grade>
<GradeBand>Ace-S</GradeBand>
<Maturity>M</Maturity>
<Region>LON</Region>
</player>
<player>
<Position>2</Position>
<Name>David Gold</Name>
<Grade>70.85</Grade>
<GradeBand>Ace-S</GradeBand>
<Maturity>M</Maturity>
<Region>LON</Region>
</player>
<etc>...</etc>
<player>
<Position>49</Position>
<Name>Steve Eginton</Name>
<Grade>66.58</Grade>
<GradeBand>Ace-H</GradeBand>
<Maturity>M</Maturity>
<Region>BRB</Region>
</player>
<player>
<Position>50</Position>
<Name>Martin Jones</Name>
<Grade>66.57</Grade>
<GradeBand>Ace-H</GradeBand>
<Maturity>M</Maturity>
<Region>MID</Region>
</player>
<shown>all</shown>
<start>1</start>
<end>50</end>
<process_time>0.0701s</process_time>
</response>
response
player,1,Andrew Robson,72.60,Ace-S,M,LON
player,2,David Gold,70.85,Ace-S,M,LON
.
.
.
player,49,Steve Eginton,66.58,Ace-H,M,BRB
player,50,Martin Jones,66.57,Ace-H,M,MID
shown,all
start,1
end,50
process_time,0.0701s
GET https://www.ebu.co.uk/members/api-3.1/ngs/ranking
Query parameters
| Parameter | Default | Description |
|---|---|---|
| page | 1 | Which page we want to retrieve. There are 50 results to a page, so to find the 222nd result, you need to retrieve page 5. |
| county | all | The region code of the county to retrieve. e.g. 'SUS’ or 'YOR’. Will only return the records of the people who have primary affiliation to that county. |
| mature | 1 | Boolean value. 1 = show only mature grades (1000+ boards); 0 = show mature and evolving grades (150+ boards). |
Response
| Field | Description |
|---|---|
| Position | The ranking of this player (with the current query parameters). |
| Name | The player’s name. |
| Grade | The grade of the player. |
| GradeBand | The grade band of the player. |
| Maturity | How mature (or reliable) the grade is. 'E’ means it is evolving (150-999 boards); ’M’ means it is mature (1000+ boards). Grades with fewer than 150 boards to support them will not appear. |
| Region | The three-character region code of the primary county of the player. |
Get public NGS partnership list
This endpoint retrieves the public ranking list of top partnerships. It currently only shows the top 50 pairs, but we hope to extend this at a future time.
HTTP Request
GET https://www.ebu.co.uk/members/api-3.1/ngs/partnerships
{
"response": {
"partnership": [
{
"Position": 1,
"Player": "Gerald Tredinnick",
"Partner": "Derek Patterson",
"PlayerRegion": "KEN",
"PartnerRegion": "KEN",
"Grade": "68.82",
"GradeBand": "Ace-S",
"Maturity": "M"
},
{
"Position": 2,
"Player": "Nick Sandqvist",
"Partner": "Tom Townsend",
"PlayerRegion": "LON",
"PartnerRegion": "LON",
"Grade": "68.73",
"GradeBand": "Ace-S",
"Maturity": "M"
},
{
"etc": "..."
},
{
"Position": 49,
"Player": "Rhona Goldenfield",
"Partner": "Bernard Goldenfield",
"PlayerRegion": "MAN",
"PartnerRegion": "MAN",
"Grade": "63.85",
"GradeBand": "Ace-D",
"Maturity": "M"
},
{
"Position": 50,
"Player": "Shahzaad Natt",
"Partner": "Nick Sandqvist",
"PlayerRegion": "LON",
"PartnerRegion": "LON",
"Grade": "63.77",
"GradeBand": "Ace-D",
"Maturity": "M"
}
],
"process_time": "0.0566s"
}
}
<response>
<partnership>
<Position>1</Position>
<Player>Gerald Tredinnick</Player>
<Partner>Derek Patterson</Partner>
<PlayerRegion>KEN</PlayerRegion>
<PartnerRegion>KEN</PartnerRegion>
<Grade>68.82</Grade>
<GradeBand>Ace-S</GradeBand>
<Maturity>M</Maturity>
</partnership>
<partnership>
<Position>2</Position>
<Player>Nick Sandqvist</Player>
<Partner>Tom Townsend</Partner>
<PlayerRegion>LON</PlayerRegion>
<PartnerRegion>LON</PartnerRegion>
<Grade>68.73</Grade>
<GradeBand>Ace-S</GradeBand>
<Maturity>M</Maturity>
</partnership>
<etc>...</etc>
<partnership>
<Position>49</Position>
<Player>Rhona Goldenfield</Player>
<Partner>Bernard Goldenfield</Partner>
<PlayerRegion>MAN</PlayerRegion>
<PartnerRegion>MAN</PartnerRegion>
<Grade>63.85</Grade>
<GradeBand>Ace-D</GradeBand>
<Maturity>M</Maturity>
</partnership>
<partnership>
<Position>50</Position>
<Player>Shahzaad Natt</Player>
<Partner>Nick Sandqvist</Partner>
<PlayerRegion>LON</PlayerRegion>
<PartnerRegion>LON</PartnerRegion>
<Grade>63.77</Grade>
<GradeBand>Ace-D</GradeBand>
<Maturity>M</Maturity>
</partnership>
<process_time>0.0566s</process_time>
</response>
response
partnership,1,Gerald Tredinnick,Derek Patterson,KEN,KEN,68.82,Ace-S,M
partnership,2,Nick Sandqvist,Tom Townsend,LON,LON,68.73,Ace-S,M
.
.
.
partnership,49,Rhona Goldenfield,Bernard Goldenfield,MAN,MAN,63.85,Ace-D,M
partnership,50,Shahzaad Natt,Nick Sandqvist,LON,LON,63.77,Ace-D,M
process_time,0.0566s
GET https://www.ebu.co.uk/members/api-3.1/ngs/partnerships
Query parameters
| Parameter | Default | Description |
|---|---|---|
| mature | 1 | Boolean value. 1 = show only mature partnership grades (1000+ boards together); 0 = show mature and evolving partnership grades (150+ boards). |
Response
| Field | Description |
|---|---|
| Position | The ranking of this partnership (with the current query parameters). |
| Player | Player 1’s name. |
| Partner | Player 2’s name. There is no ordering of the two players, despite using the terms 'Player’ and 'Partner’. |
| PlayerRegion | The three-character region code of the primary county of Player 1. |
| PartnerRegion | The three-character region code of the primary county of Player 2. |
| Grade | The grade of the partnership. |
| GradeBand | The grade band of the partnership. |
| Maturity | How mature (or reliable) the grade is. 'E’ means it is evolving (150-999 boards); ’M’ means it is mature (1000+ boards). Grades with fewer than 150 boards to support them will not appear. |
Get session strength of field
This endpoint retrieves the strength of field for a session. This is made available as a simpler (and slightly faster) alternative to GET /session/{id} for services which want to display the strength on a website.
Requires you to authenticate as the club/county of the session you’re querying for.
HTTP Request
GET https://www.ebu.co.uk/members/api-3.1/ngs/sof/00987654-000001
{
"response": {
"login": "club",
"success": "52.33",
"process_time": "0.3615s"
}
}
{
"response": {
"login": "club",
"status": "P2PChargeRateOmitted",
"failure": "This session has no SOF",
"process_time": "0.5752s"
}
}
<response>
<login>club</login>
<success>52.33</success>
<process_time>0.3615s</process_time>
</response>
<response>
<login>club</login>
<status>P2PChargeRateOmitted</status>
<failure>This session has no SOF</failure>
<process_time>0.5752s</process_time>
</response>
response
login,club
success,52.33
process_time,0.3615s
response
login,county
status,P2PChargeRateOmitted
failure,This session has no SOF
process_time,0.5752s
GET https://www.ebu.co.uk/members/api-3.1/ngs/sof/{id}
Response
| Field | Description |
|---|---|
| success | If successful, returns this with the strength of field. |
| failure | If unsuccessful, returns a message here, along with the 'status’ field below. |
The status of an NGS session can include, but is not limited to, the following values.
| Status | Description |
|---|---|
| notPairs | Used in the early days of the NGS, when we did not support teams events. |
| unusual event type | This event type is not supported by the NGS. Usually means an individual. |
| Teams - Unusual Scoring Method | The scoring method for the pairwise data is not supported by the NGS. |
| tooFewOKPairs | A session requires a certain proportion of recognised pairs to be graded. Usually means there are too many guests. |
| tooFewPairs | The session is too small to process. |
| P2PChargeRateOmitted | Certain events are not graded based on the UM subscription rate. e.g. supervised play sessions. |
| badScores | The scores are outside of the tolerance for a session to be graded. Usually means there are too many adjusted boards. |
| SwissMiss | Swiss Pairs event without required data to be processed. |
| teams event - no pairs data | A teams event without the pairwise data (usually cross-IMPs) required to grade it. |
| multiSibling | The session is part of a multi-session event and the SOF will appear on the parent session. |
| pairIdMismatch | Multi-session event with mismatched pairs between sessions. |
Member information
There are a few other API calls which deal with membership data not covered in the details or ngs endpoints, above.
Get list of magazines
This endpoint retrieves the URLs for the past six editions of English Bridge magazine. This information should only be used by the member accessing it. Never share it with anyone else.
Editions which are more than a year old are publicly available and can be found on our website.
HTTP Request
GET https://www.ebu.co.uk/members/api-3.1/magazines
{
"response": {
"login": "member",
"Magazines": [
{
"month": "August",
"year": "2017",
"url": "https://view.pagetiger.com/id"
},
{
"etc": "..."
}
],
"process_time": "1.5070s"
}
}
<response>
<login>member</login>
<Magazines>
<month>August</month>
<year>2017</year>
<url>https://view.pagetiger.com/id</url>
</Magazines>
<etc>...</etc>
<process_time>1.5070s</process_time>
</response>
response
login,member
Magazines,August,2017,https://view.pagetiger.com/id
etc.
process_time,1.5070s
GET https://www.ebu.co.uk/members/api-3.1/magazines
Response
A list of Magazines elements, with the following data.
| Field | Description |
|---|---|
| month | The month of the magazine. |
| year | The year of the magazine. |
| url | The URL of the magazine. We host our electronic magazines on the PageTiger service. |
Get list of transactions
This endpoint retrieves all the transactions associated with the account. This includes all invoices and credit notes and, for clubs and counties, Universal Membership statements. It does not include receipts, such as credit card payments.
HTTP Request
GET https://www.ebu.co.uk/members/api-3.1/transactions
{
"response": {
"login": "member",
"Balance": 0,
"Transactions": [
{
"Date": "20170407120000",
"Text": "Test Online Booking",
"Total": 19,
"Paid": 19,
"Outstanding": 0,
"ID": 987654,
"InvoiceNumber": "INV-1234",
"Type": "invoice"
},
{
"Date": "20170411120000",
"Text": "Reverse Test Online Booking",
"Total": -19,
"Paid": -19,
"Outstanding": 0,
"ID": 987655,
"InvoiceNumber": "CRN-1234",
"Type": "creditnote"
}
],
"process_time": "4.4550s"
}
}
<response>
<login>member</login>
<Balance>0</Balance>
<Transactions>
<Date>20170407120000</Date>
<Text>Test Online Booking</Text>
<Total>19</Total>
<Paid>19</Paid>
<Outstanding>0</Outstanding>
<ID>987654</ID>
<InvoiceNumber>INV-1234</InvoiceNumber>
<Type>invoice</Type>
</Transactions>
<Transactions>
<Date>20170411120000</Date>
<Text>Reverse Test Online Booking</Text>
<Total>-19</Total>
<Paid>-19</Paid>
<Outstanding>0</Outstanding>
<ID>987655</ID>
<InvoiceNumber>CRN-1234</InvoiceNumber>
<Type>creditnote</Type>
</Transactions>
<process_time>4.4550s</process_time>
</response>
response
login,member
Balance,0
Transactions,20170407120000,Test Online Booking,19,19,0,987654,INV-1234,invoice
Transactions,20170411120000,Reverse Test Online Booking,-19,-19,0,987655,CRN-1234,creditnote
process_time,4.4550s
GET https://www.ebu.co.uk/members/api-3.1/transactions
Response
Returns a list of Transactions elements, containing the following data.
Also returns a Balance element which contains the current account balance (a positive number means the member owes the EBU money; a negative number means the member is in credit). Balances do not include shop transactions.
| Field | Description |
|---|---|
| Date | The date of the transaction. |
| Text | A description of the transaction. |
| Total | The amount of the transaction. Will be negative for a credit note. |
| Paid | The amount that has been paid/allocated so far. |
| Outstanding | The amount that has not been paid/allocated so far. |
| ID | An internal ID for EBU use. Won’t be of any use to anyone else. |
| InvoiceNumber | The invoice or credit note number. Will start either INV- or CRN-. This can be used to retrieve a PDF of the invoice (see below). |
| Type | ‘invoice’ or 'creditnote’, depending on what it is. |
Retrieving a PDF invoice/credit note
To get a PDF version of the invoice or credit note, you can use this URL:
https://www.ebu.co.uk/members/utilities/invoice.php?inum=CRN-1234&user={uid}&token={token}
This requires an authentication token that you need to generate through the login endpoint, above, and the invoice/credit note number. Naturally, you can only access a document that was issued to your account.
Get masterpoints data
This endpoint retrieves masterpoint information for a member. It lists every batch that has been awarded to the member, as well as overall totals.
HTTP Request
GET https://www.ebu.co.uk/members/api-3.1/masterpoints
{
"response": {
"login": "member",
"Lines": [
{
"Description": "EBU Summer Meeting",
"EventID": "6",
"MPYear": "2016",
"LocalPoints": "0",
"BluePoints": "0",
"GreenPoints": "540",
"GoldPoints": "540",
"NetPoints": "0",
"CreatedDate": "2016-09-09",
"Comments": "EBU Summer Meeting - Harold Poster"
},
{
"etc": "..."
},
{
"Description": "North East Direct Credit",
"EventID": "33",
"MPYear": "2001",
"LocalPoints": "48",
"BluePoints": "0",
"GreenPoints": "0",
"GoldPoints": "0",
"NetPoints": "0",
"CreatedDate": "2001-06-28",
"Comments": ""
}
],
"Totals": {
"Description": "Premier National Master",
"Comments": "Total Points: 42039 (Local: 19025, Blue: 0, Green: 21898, Net: 1116, Gold: 0.86)",
"Locals": "19025",
"Blues": "0",
"Greens": "21898",
"Nets": "1116",
"Total": "42039",
"Golds": "0.86",
"RankCode": "4000"
},
"process_time": "0.0679s"
}
}
<response>
<login>member</login>
<Lines>
<Description>EBU Summer Meeting</Description>
<EventID>6</EventID>
<MPYear>2016</MPYear>
<LocalPoints>0</LocalPoints>
<BluePoints>0</BluePoints>
<GreenPoints>540</GreenPoints>
<GoldPoints>540</GoldPoints>
<NetPoints>0</NetPoints>
<CreatedDate>2016-09-09</CreatedDate>
<Comments>EBU Summer Meeting - Harold Poster</Comments>
</Lines>
<etc>...</etc>
<Lines>
<Description>North East Direct Credit</Description>
<EventID>33</EventID>
<MPYear>2001</MPYear>
<LocalPoints>48</LocalPoints>
<BluePoints>0</BluePoints>
<GreenPoints>0</GreenPoints>
<GoldPoints>0</GoldPoints>
<NetPoints>0</NetPoints>
<CreatedDate>2001-06-28</CreatedDate>
<Comments></Comments>
</Lines>
<Totals>
<Description>Premier National Master</Description>
<Comments>Total Points: 42039 (Local: 19025, Blue: 0, Green: 21898, Net: 1116, Gold: 0.86)</Comments>
<Locals>19025</Locals>
<Blues>0</Blues>
<Greens>21898</Greens>
<Nets>1116</Nets>
<Total>42039</Total>
<Golds>0.86</Golds>
<RankCode>4000</RankCode>
</Totals>
<process_time>0.0679s</process_time>
</response>
response
login,member
Lines,EBU Summer Meeting,6,2016,0,0,540,540,0,2016-09-09,EBU Summer Meeting - Harold Poster
.
.
.
Lines,North East Direct Credit,33,2001,48,0,0,0,0,2001-06-28,
Totals,Premier National Master,Total Points: 42039 (Local: 19025, Blue: 0, Green: 21898, Net: 1116, Gold: 0.86),19025,0,21898,1116,42039,0.86,4000
process_time,0.1482s
GET https://www.ebu.co.uk/members/api-3.1/masterpoints
Response
A series of Lines elements, with the following fields:
| Field | Description |
|---|---|
| Description | A description of the event that this award was entered as. These can be quite generic in the case of club and county direct uploads (see Comments, below). |
| EventID | A numeric ID for the event. Should usually match the Description above. |
| MPYear | The year of this award. |
| LocalPoints | The local (black) points that were won in this award. |
| BluePoints | The blue points that were won in this award. Note that for blue and green points, awards are expressed on the same scale as local points. So winning 0.25 green points for a Swiss match will be shown as '25’. |
| GreenPoints | The green points that were won in this award. |
| GoldPoints | The gold point-eligible green points that were awarded. This is not the same as the gold points, but can be used to calculate them. For example, winning 1.5 Gold Points in an event will be shown as '750’. |
| NetPoints | The net points that were won in this award. These are now no longer issued, but are still shown for interest. They may be removed at some future date. |
| CreatedDate | The date that the award was created. |
| Comments | Some additional text about the award’s batch. This can be more specific than Description, above, especially in the case of monthly awards processed by the UM system. |
Plus a Totals element, with the following fields:
| Field | Description |
|---|---|
| Description | A description of the masterpoint rank. |
| Comments | Some text that can be printed to show the member’s masterpoint totals. |
| Locals | The total number of local points. |
| Blues | The total number of blue points (normalised to the same scale as local points - see above). |
| Greens | The total number of green points (ditto). |
| Nets | The total number of net points. |
| Total | The total number of masterpoints. Caution: this might not always be the sum of locals + blues + greens + nets. |
| Golds | The current gold point total, as of today. Gold points depreciate every year, so this total might change even if the member does not play. |
| RankCode | A numerical version of the masterpoint rank. The lower the number, the higher the rank. |
Change password
This endpoint allows a member, club or county to change their password. The old password must be supplied for this to work - a token is not good enough on its own. If the login is done with a token, that token will remain intact. All other authentication tokens will be expired, so you can’t remain logged in on another computer.
HTTP Request
POST https://www.ebu.co.uk/members/api-3.1/password
{
"response": {
"login": "member",
"success": "Password changed",
"process_time": "0.2759s"
}
}
<response>
<login>member</login>
<success>Password changed</success>
<process_time>0.2759s</process_time>
</response>
response
login,member
success,Password changed
process_time,0.2759s
POST https://www.ebu.co.uk/members/api-3.1/password
Query parameters
| Parameter | Default | Description |
|---|---|---|
| old | none | The old password. This needs to be the actual password. You cannot use a token to change a password. |
| new | none | The new password. |
Response
| Field | Description |
|---|---|
| success | If successful. |
| failure | If not. |
Get resources
This endpoint retrieves the URLs of some EBU resources if the account has permission to access them. This currently means the EBUScore software and Club Membership Handbooks for clubs and counties; and EBUScore and the Teachers Zone for members. This information should only be used by the account accessing it. Never share it with anyone else.
HTTP Request
GET https://www.ebu.co.uk/members/api-3.1/resources
{
"response": {
"login": "member",
"TeachersZone": "url",
"EBUScore": {
"Folder": "folder path",
"PairsScorer": "file name",
"TeamsScorer": "file name",
"SwissTeamsScorer": "file name",
"SwissPairsScorer": "file name",
"IndividualScorer": "file name"
},
"process_time": "2.5959s"
}
}
{
"response": {
"login": "club",
"CMHURL": "http://www.ebu.co.uk/url",
"EBUScore": {
"Folder": "folder path",
"PairsScorer": "file name",
"TeamsScorer": "file name",
"SwissTeamsScorer": "file name",
"SwissPairsScorer": "file name",
"IndividualScorer": "file name"
},
"process_time": "2.5959s"
}
}
<response>
<login>member</login>
<TeachersZone>url</TeachersZone>
<EBUScore>
<Folder>folder path</Folder>
<PairsScorer>file name</PairsScorer>
<TeamsScorer>file name</TeamsScorer>
<SwissTeamsScorer>file name</SwissTeamsScorer>
<SwissPairsScorer>file name</SwissPairsScorer>
<IndividualScorer>file name</IndividualScorer>
</EBUScore>
<process_time>2.5949s</process_time>
</response>
<response>
<login>club</login>
<CMHURL>http://www.ebu.co.uk/url</CMHURL>
<EBUScore>
<Folder>folder path</Folder>
<PairsScorer>file name</PairsScorer>
<TeamsScorer>file name</TeamsScorer>
<SwissTeamsScorer>file name</SwissTeamsScorer>
<SwissPairsScorer>file name</SwissPairsScorer>
<IndividualScorer>file name</IndividualScorer>
</EBUScore>
<process_time>2.5959s</process_time>
</response>
response
login,member
TeachersZone,url
EBUScore,folder path,file name,file name,file name,file name,file name
process_time,2.5959s
response
login,club
CMHURL,http://www.ebu.co.uk/url
EBUScore,folder path,file name,file name,file name,file name,file name
process_time,2.5959s
GET https://www.ebu.co.uk/members/api-3.1/resources
Response
| Field | Description |
|---|---|
| TeachersZone | The location of the teachers zone (only available to registered teachers). This can be found on the EBED website, so for example if the value is 'zone1234’ then you need to direct the user to 'http://www.ebedcio.org.uk/zone1234’. |
| CMHURL | The full path of the Club Management Handbook (only available to registered clubs). |
| EBUScore | Information about how to download the EBUScore scoring program. |
| Folder | The path of the folder. e.g. if the value is ’/documents/ebuscore/1234’ then you can find the below files in http://www.ebu.co.uk/documents/ebuscore/1234/’. This value changes periodically. |
| PairsScorer | The file name of the PairsScorer program. Append this to the folder path above to download it. |
| TeamsScorer | The file name of the TeamsScorer program. |
| SwissTeamsScorer | The file name of the SwissTeamsScorer program. |
| SwissPairsScorer | The file name of the SwissPairsScorer program. |
| IndividualScorer | The file name of the IndividualScorer program. |
Club admin
A series of endpoints for club administration, mostly involving dealing with club members.
Verify a member
A simple endpoint which verifies if a given EBU number matches a given surname. Used in multiple places on the EBU website to verify that an EBU number being submitted has not been mis-typed.
HTTP Request
GET https://www.ebu.co.uk/members/api-3.1/members/00987654/verify
{
"response": {
"login": "club",
"success": "EBU# exists",
"forenames": "Billy",
"surname": "Shears",
"process_time": "0.8747s"
}
}
<response>
<login>club</login>
<success>EBU# exists</success>
<forenames>Billy</forenames>
<surname>Shears</surname>
<process_time>0.8747s</process_time>
</response>
response
login,club
success,EBU# exists
forenames,Billy
surname,Shears
process_time,0.8747s
GET https://www.ebu.co.uk/members/api-3.1/members/{id}/verify
Query parameters
| Parameter | Default | Description |
|---|---|---|
| surname | none | The surname of the person you are checking. Has to be complete: ‘Smith’ will not match with 'Smithson’ or 'Smith-Peters’. |
Response
Returns success if the check passed, failure otherwise. If it passed, it also returns:
| Field | Description |
|---|---|
| forenames | The forenames of the person we’re checking. |
| surname | Their surname. Normally will be the same as the one you’re checking, but this confirms the capitalisation we have on our database. |
List club members
This endpoint retrieves a list of all the members of the club, with some basic data (including NGS grade) included.
HTTP Request
GET https://www.ebu.co.uk/members/api-3.1/members
{
"response": {
"login": "club",
"Members": [
{
"Surname": "Billy",
"Forenames": "Shears",
"EBU": "00987654",
"Anonymous": 0,
"Roles": [
"scorer",
"member"
],
"Grade": "60.05",
"GradeBand": "King",
"Maturity": "E"
}
],
"process_time": "1.3661s"
}
}
<response>
<login>club</login>
<Members>
<Surname>Billy</Surname>
<Forenames>Shears</Forenames>
<EBU>00987654</EBU>
<Anonymous>0</Anonymous>
<Roles>
<ListItem>scorer</ListItem>
<ListItem>member</ListItem>
</Roles>
<Grade>60.05</Grade>
<GradeBand>King</GradeBand>
<Maturity>E</Maturity>
</Members>
<process_time>1.3661s</process_time>
</response>
response
login,club
Members,Shears,Billy,00987654,0,scorer,member,60.05,King,E
process_time,1.3661s
GET https://www.ebu.co.uk/members/api-3.1/members
Response
A list of Members elements, each containing the following data:
| Field | Description |
|---|---|
| Surname | The surname of the member. |
| Forenames | The forenames of the member. |
| EBU | The EBU number of the member. |
| Anonymous | A boolean value for whether they have chosen to be anonymous to the EBU. |
| Roles | A list of roles that the member has at the club. Currently just limited to 'member’ and 'scorer’, but we may use this field to allow clubs to assign chairmen and secretaries and other roles through My EBU. |
| Grade | The NGS grade of the member, if they have one, and if they have permitted it to be published. |
| GradeBand | The grade band of the member. |
| Maturity | The maturity of the NGS grade. ’M’ means 1000+ graded boards played, 'E’ means 150-999. Those who have played fewer than 150 boards will not have a public grade. |
Get member data
This endpoint retrieves data about a member. The extent of the data that gets returns depends on the member’s permission settings for that club.
HTTP Request
GET https://www.ebu.co.uk/members/api-3.1/members/00987654
{
"response": {
"login": "club",
"EBU": "00987654",
"Permission": "00",
"Scorer": "1",
"Grade": "60.05",
"GradeBand": "King",
"GradeMaturity": "E",
"MPRank": "Premier National Master",
"Surname": "Billy",
"Forenames": "Shears",
"RegionCode": "OXF",
"RegionName": "Oxfordshire",
"Town": "Aylesbury",
"Anonymous": "0",
"Partial_Postcode": "HP19",
"Warning": "You do not have permission to view this member's full details",
"process_time": "3.0091s"
}
}
{
"response": {
"login": "club",
"EBU": "00987655",
"Permission": "11",
"Scorer": "0",
"MPRank": "Life Master",
"Surname": "Willy",
"Forenames": "Shears",
"RegionCode": "DIU",
"RegionName": "Direct UK",
"Town": "Myton",
"Anonymous": "0",
"Address": "123 Some Road",
"AppearInMagazine": "1",
"Country": "UK",
"County": "Countyshire",
"DOB": "",
"Email": "email@ebu.co.uk",
"Initials": "WS",
"MagazinePreference": "All Editions, No Diary",
"NGSPreference": "Public Grade and Partnerships",
"Postcode": "CC1 1AB",
"ReceiveMassEmails": "1",
"ReceiveOtherMailings": "0",
"Tel1": "01296 987654",
"Tel2": "01296 987655",
"Title": "Mr",
"process_time": "3.0091s"
}
}
<response>
<login>club</login>
<EBU>00987654</EBU>
<Permission>00</Permission>
<Scorer>1</Scorer>
<Grade>60.05</Grade>
<GradeBand>King</GradeBand>
<GradeMaturity>E</GradeMaturity>
<MPRank>Premier National Master</MPRank>
<Surname>Shears</Surname>
<Forenames>Billy</Forenames>
<RegionCode>OXF</RegionCode>
<RegionName>Oxfordshire</RegionName>
<Town>Aylesbury</Town>
<Anonymous>0</Anonymous>
<Partial_Postcode>HP19</Partial_Postcode>
<Warning>You do not have permission to view this member's full details</Warning>
<process_time>3.0091s</process_time>
</response>
<response>
<login>club</login>
<EBU>00987655</EBU>
<Permission>11</Permission>
<Scorer>0</Scorer>
<MPRank>Life Master</MPRank>
<Surname>Shears</Surname>
<Forenames>Willy</Forenames>
<RegionCode>DIU</RegionCode>
<RegionName>Direct UK</RegionName>
<Town>Myton</Town>
<Anonymous>0</Anonymous>
<Address>123 Some Road</Address>
<AppearInMagazine>1</AppearInMagazine>
<Country>UK</Country>
<County>Countyshire</County>
<DOB></DOB>
<Email>email@ebu.co.uk</Email>
<Initials>WS</Initials>
<MagazinePreference>All Editions, No Diary</MagazinePreference>
<NGSPreference>Public Grade and Partnerships</NGSPreference>
<Postcode>CC1 1AB</Postcode>
<ReceiveMassEmails>1</ReceiveMassEmails>
<ReceiveOtherMailings>0</ReceiveOtherMailings>
<Tel1>01296 987654</Tel1>
<Tel2>01296 987655</Tel2>
<Title>Mr</Title>
<process_time>3.0091s</process_time>
</response>
response
login,club
EBU,00987654
Permission,00
Scorer,1
Grade,60.05
GradeBand,King
GradeMaturity,E
MPRank,Premier National Master
Surname,Shears
Forenames,Billy
RegionCode,OXF
RegionName,Oxfordshire
Town,Aylesbury
Anonymous,0
Partial_Postcode,HP19
Warning,You do not have permission to view this member's full details
process_time,3.0091s
response
login,club
EBU,00987655
Permission,11
Scorer,0
MPRank,
Surname,Shears
Forenames,Willy
RegionCode,DIU
RegionName,Direct UK
Town,Myton
Anonymous,0
Address,123 Some Road
AppearInMagazine,1
Country,UK
County,Countyshire
DOB,
Email,email@ebu.co.uk
Initials,WS
MagazinePreference,All Editions, No Diary
NGSPreference,Public Grade and Partnerships
Postcode,CC1 1AB
ReceiveMassEmails,1
Tel1,01296 987654
Tel2,01296 987655
Title,Mr
process_time,3.0091s
GET https://www.ebu.co.uk/members/api-3.1/members/{id}
Response
The fields here should mostly mirror the ones listed above in the Get member details section, and will not be repeated here. There are some additional ones, though.
| Field | Description |
|---|---|
| Permission | A two-bit field containing the read and write permission that the club has over the member’s record, in that order. The left bit set to 1 means that the club has access to the member’s full details. The right bit set to 1 means that the club can edit the member’s details on their behalf. |
| Scorer | A boolean value for whether this member is a scorer at the club. |
| Partial_Postcode | In the case of members who have not given permission to view their details, this will show the first part of the postcode, to help with localising this member (and checking you have the right person). e.g. For the EBU office this will simply show 'HP19’. |
Check EBU number
This endpoint retrieves just the name of an EBU member. It is intended to be a faster version of the GET /members/{id} call, above.
HTTP Request
GET https://www.ebu.co.uk/members/api-3.1/members/00987654/check
{
"response": {
"login": "club",
"Surname": "Billy",
"Forenames": "Shears",
"process_time": "0.6640s"
}
}
<response>
<login>club</login>
<Surname>Shears</Surname>
<Forenames>Billy</Forenames>
<process_time>0.6640s</process_time>
</response>
response
login,club
Surname,Shears
Forenames,Billy
process_time,0.6640s
GET https://www.ebu.co.uk/members/api-3.1/{id}/check
Response
| Field | Description |
|---|---|
| Surname | The member’s surname. |
| Forenames | The member’s forenames. |
Update member data
This endpoint writes data about a member. The club needs to have write permission in order to do this. This permission is assumed for members that the club created directly, but otherwise it must be set by the member through their own My EBU.
This procedure call expects a JSON string to be sent in the data URL parameter. This should be in the same format as the GET members/{id} call, above.
Also see Record details/Update member details above for some additional notes.
HTTP Request
POST https://www.ebu.co.uk/members/api-3.1/members/00987654
{
"response": {
"login": "club",
"Amending": [
"Field Tel1 amended to 01296 317200"
],
"success": "Member updated",
"process_time": "2.8970s"
}
}
{
"response": {
"login": "club",
"Amending": [],
"failure": "You do not have permission to amend this record",
"process_time": "2.2735s"
}
}
<response>
<login>club</login>
<Amending>Field Tel1 amended to 01296 317200</Amending>
<success>Member updated</success>
<process_time>2.8970s</process_time>
</response>
<response>
<login>club</login>
<failure>You do not have permission to amend this record</failure>
<process_time>2.2735s</process_time>
</response>
response
login,club
Amending,Field Tel1 amended to 01296 317200
success,Member updated
process_time,2.8970s
response
login,club
failure,You do not have permission to amend this record
process_time,2.2735s
POST https://www.ebu.co.uk/members/api-3.1/members/{id}
Query parameters
| Parameter | Default | Description |
|---|---|---|
| data | none | JSON string of the changes that are being made, using the same field names as are returned by the corresponding GET call. You can leave fields out without worrying about those fields being erased, so you only need to submit the ones that are changing. |
Response
Returns success or failure depending on if it works.
| Field | Description |
|---|---|
| Amending | A list of changes that were actioned. Useful to check against to make sure you got the field names correct. |
Create new player record
This endpoint lets a club create a new member record. Clubs are advised to be cautious about doing this, and should take every effort to ensure that they are not creating a duplicate record for someone already on the system.
HTTP Request
POST https://www.ebu.co.uk/members/api-3.1/members/create
{
"response": {
"login": "club",
"EBU": "00987654",
"Permission": "00",
"Surname": "Brown",
"Forenames": "Jackson",
"RegionName": "Yorkshire",
"Anonymous": "0",
"AppearInMagazine": "1",
"DOB": " 2 Jan 2001",
"MagazinePreference": "All Editions + Diary",
"NGSPreference": "Public Grade and Partnerships",
"ReceiveMassEmails": "1",
"ReceiveOtherMailings": "0",
"process_time": "2.8207s"
}
}
<response>
<login>club</login>
<EBU>00987654</EBU>
<Permission>00</Permission>
<Surname>Brown</Surname>
<Forenames>Jackson</Forenames>
<RegionName>Yorkshire</RegionName>
<Anonymous>0</Anonymous>
<AppearInMagazine>1</AppearInMagazine>
<DOB> 2 Jan 2001</DOB>
<MagazinePreference>All Editions + Diary</MagazinePreference>
<NGSPreference>Public Grade and Partnerships</NGSPreference>
<ReceiveMassEmails>1</ReceiveMassEmails>
<process_time>2.8207s</process_time>
</response>
response
login,club
EBU,00987654
Permission,00
Surname,Brown
Forenames,Jackson
RegionName,Yorkshire
Anonymous,0
AppearInMagazine,1
DOB, 2 Jan 2001
MagazinePreference,All Editions + Diary
NGSPreference,Public Grade and Partnerships
ReceiveMassEmails,1
process_time,2.8207s
GET https://www.ebu.co.uk/members/api-3.1/members/create
Query parameters
| Parameter | Default | Description |
|---|---|---|
| forenames | none | The forenames of the new player (required) |
| surname | none | The surname of the new player (required) |
| member | 0 | Whether this player is a member of the club or not. It’s important to set this to '1’ if they are indeed a member. Otherwise you will not have permission to amend them further and they will just be a generic 'Contact’. |
| dob | none | The date of birth of the new player, in the format yyyy-mm-dd. This is a field that cannot be amended through POST /members/{id}, so needs to be set now if at all. Members can always set their date of birth by contacting the EBU office, though. A date of birth is required for juniors. |
Response
Most of the response data just echoes back the information you supplied, or tells you what the default settings are. However, you will want to note the EBU number.
| Field | Description |
|---|---|
| EBU | The new EBU number of the member. |
| Permission | The permission bytes. Will be either '11’ if you made them a member of your club (giving you read/write privileges over their account) or '00’ if you didn’t (giving you no privileges). |
| Surname | The surname you supplied. |
| Forenames | The forenames you supplied |
| RegionName | The primary county of the new record. Will take on whatever county the club is affiliated to. If this is not correct, the member can change this by contacting the EBU office. |
| Anonymous | Will always be 0 (false). If the member wishes to be anonymous, you can set this by editing the new record (if you have permission). |
| AppearInMagazine | Will always be 1 (true). If the member wishes to hide themselves from masterpoint promotion lists in the magazine, you can set this by editing the new record. |
| DOB | The data of birth you supplied. If you made a mistake, the member can correct this by contacting the EBU office. |
| MagazinePreference | Will always be 'All Editions + Diary’. You can change this, and the fields below, by editing the new record. |
| NGSPreference | Will always be 'Public Grade and Partnerships’. |
| ReceiveMassEmails | Will always be 1 (true). |
Join a member to the club
This endpoint joins up a new member to the club. They must have an EBU record already to do this. If they don’t, use the POST /members/create endpoint, above.
HTTP Request
POST https://www.ebu.co.uk/members/api-3.1/members/00987654/add
{
"response": {
"login": "club",
"success": "Member added to club",
"process_time": "4.9226s"
}
}
<response>
<login>club</login>
<success>Member added to club</success>
<process_time>4.9226s</process_time>
</response>
response
login,club
success,Member added to club
process_time,4.9226s
POST https://www.ebu.co.uk/members/api-3.1/members/{id}/add
Response
Simply returns a success or failure message.
Unjoin a member from the club
This endpoint removes a member from the club. Note that if this member is not a member anywhere else, and has not joined the EBU directly, this will remove them as a member of the EBU too.
HTTP Request
DELETE https://www.ebu.co.uk/members/api-3.1/members/00987654
{
"response": {
"login": "club",
"success": "Member removed",
"process_time": "4.1548s"
}
}
<response>
<login>club</login>
<success>Member removed</success>
<process_time>3.0630s</process_time>
</response>
response
login,club
success,Member removed
process_time,3.9355s
DELETE https://www.ebu.co.uk/members/api-3.1/members/{id}
Response
Simply returns a success or failure message.
Statements and invoices
This is covered in GET /transactions under Member Information above. The procedure call works the same way for members as it does for clubs/counties.
Get resources
This is covered in GET /resources under Member Information above. The procedure call works the same way for members as it does for clubs/counties, although of course there are slightly different resources available.
Search for members
This endpoint lets you search for EBU records by name and is used when you don’t have the EBU number. Users need to be cautious here, as the amount of information returned is necessarily limited, so it is not always possible to tell if the person you’re looking for is indeed the person that is returned. You can be pretty safe in assuming that there is only one Percival Hyde-Wilson living in Ipswich, but you can’t be as sure about a John Brown living in London.
HTTP Request
GET https://www.ebu.co.uk/members/api-3.1/members/surname/nameson
{
"response": {
"login": "club",
"Records": [
{
"Surname": "Nameson",
"Forenames": "Donald",
"EBU": "00987654",
"Town": "Aylesbury"
}
],
"process_time": "1.2189s"
}
}
<response>
<login>club</login>
<Records>
<Surname>Nameson</Surname>
<Forenames>Donald</Forenames>
<EBU>00987654</EBU>
<Town>Aylesbury</Town>
</Records>
<process_time>1.2189s</process_time>
</response>
response
login,club
Records,Nameson,Donald,00987654,Aylesbury
process_time,1.2189s
GET https://www.ebu.co.uk/members/api-3.1/members/surname/{surname}
Query parameters
| Parameter | Default | Description |
|---|---|---|
| forenames | none | Optional parameter to restrict results to people with this forename. The surname must be complete ('Smith’ will not return people called 'Smithson’), but forenames can be partial ('P’ and 'Pete’ will return people called 'Peter’). |
Response
Returns a Records object with a list of results, each with the following fields.
| Field | Description |
|---|---|
| Surname | The surname, as held on our database. |
| Forenames | The forenames, as held on our database. |
| EBU | The record’s EBU number. |
| Town | The town of the member. Used to localise searches. |
Get member promotions
This endpoint retrieves a list of the masterpoint promotions that the club membership has earned over the past year. Of course, “club membership” here means current members. If someone was promoted six months ago and then resigned from the club they will not appear in the report. And someone who was promoted six months ago when they were not a club member, but have joined since, will appear in the report.
Note: this procedure can be pretty slow for large clubs.
HTTP Request
GET https://www.ebu.co.uk/members/api-3.1/promotions
{
"response": {
"login": "club",
"Members": [
{
"EBU": "00987654",
"Name": "Tony Goldblum",
"Promotions": [
{
"Date": "2016-09-01",
"From": "Unranked",
"To": "Local Master"
}
]
},
{
"EBU": "00987655",
"Name": "Jeff Goldblum",
"Promotions": [
{
"Date": "2016-12-01",
"From": "3 Star Premier Tournament Master",
"To": "4 Star Premier Tournament Master"
}
]
}
],
"process_time": "2.3973s"
}
}
<response>
<login>club</login>
<Members>
<EBU>00987654</EBU>
<Name>Tony Goldblum</Name>
<Promotions>
<ListItem>
<Date>2016-09-01</Date>
<From>Unranked</From>
<To>Local Master</To>
</ListItem>
</Promotions>
</Members>
<Members>
<EBU>00987655</EBU>
<Name>Jeff Goldblum</Name>
<Promotions>
<ListItem>
<Date>2016-12-01</Date>
<From>3 Star Premier Tournament Master</From>
<To>4 Star Premier Tournament Master</To>
</ListItem>
</Promotions>
</Members>
<process_time>2.3973s</process_time>
</response>
response
login,club
Members,00987654,Tony Goldblum,Array
Members,00987655,Jeff Goldblum,Array
process_time,2.3973s
(this one leaves out the key information, so is fairly useless)
GET https://www.ebu.co.uk/members/api-3.1/promotions
Response
Returns a list of Members objects, each containing:
| Field | Description |
|---|---|
| EBU | The EBU number of the member. |
| Name | The name of the member. |
| Promotions | A list of promotions earned in the past year (there can of course be more than one), with the date and the rank information. We calculate promotions once a month, so the date will always be the 1st of the month. |
Reports
These endpoints run some reports that club administrators may find useful for managing their membership lists. Examples are omitted here, but they all return lists of members, with various data fields.
Members who haven’t played in a while
GET https://www.ebu.co.uk/members/api-3.1/members/lastdate
This report returns a list of members who have not played at this club in the past 12 months. This can be useful for weeding out members who should have lapsed.
Returns a list of Members, with the following fields:
| Field | Description |
|---|---|
| EBU | The EBU number of the member. |
| Name | The name of the member. |
| LastDatePlayed | The last date that the member played at the club, or 'Never’ if they never have. |
Non-members who are playing at the club
GET https://www.ebu.co.uk/members/api-3.1/non-member-players
This report returns a list of people who have played at the club in the past 12 months and who are not members of the club. This can be useful for identifying people who should be members.
Returns a list of Members, with the following fields:
| Field | Description |
|---|---|
| EBU | The EBU number of the member. |
| Name | The name of the member. |
| Sessions | Number of sessions played at the club in the past year. |
Guests who are playing at the club
GET https://www.ebu.co.uk/members/api-3.1/members/lastdate
This report returns a list of all the people who have played at the club in the past year who were not given an EBU number (they were 'guests’). People who appear multiple times on this report are very likely to be mistakes.
Returns a list of Guests, with the following fields:
| Field | Description |
|---|---|
| Date | The date that this guest played. |
| Session | The session ID in which they played. |
| Name | The name assigned to them. |
Contacts created but who have not joined
GET https://www.ebu.co.uk/members/api-3.1/contacts
This report lists the contacts which the club has created, but who are not currently members. This can be useful to track down people who have been created, since they (obviously) don’t appear in the membership list and if they have a common name it may not be easy to find them by normal search.
Returns a list of Contacts, with the following fields:
| Field | Description |
|---|---|
| EBU | The EBU number of the contact. |
| DateCreated | The date that we created this contact. |
| Surname | The surname of the contact. |
| Forenames | The forenames of the contact. |
Submitting sessions
This section describes how to submit a session file to the EBU systems. The process can be a little unwieldy, so if you’re developing an integration it would definitely be a good idea to contact Michael Clark for assistance. He can give you access to a test account, and will be able to check your submissions more thoroughly than you are able.
Submission Workflow
<form enctype="multipart/form-data"
action="https://www.ebu.co.uk/members/api/p2p/parse-usebio-1.1.php"
method="POST">
Upload P2P File: <input id="file" name="myfile" type="file"/>
<input type="submit" name="validate_upload" value="Upload"/>
</form>
The general workflow for submitting a session is as follows:
- Produce the USEBIO file. How to do that is beyond the scope of this document. See http://www.usebio.org for more details.
- Submit the USEBIO file to the EBU’s parser at https://www.ebu.co.uk/members/api/p2p/parse-usebio-1.1.php. The file parameter name needs to be myfile. This returns a JSON object with all the session data that you need.
- If the JSON object shows errors, deal with them.
- It’s a good idea to send a request to
GET /session-date/{date}to check if we’ve submitted this session before, and to check if we should also be submitting this session to a Sim Pairs event. - Extract all the players from the JSON object and gather them into an array. Pass this to the
POST /submission/check-playersprocedure. - When this request returns, deal with any mismatches and bad EBU numbers. These will cause the final submission to fail otherwise. Update the JSON object with the check keys (this is a check field in the player object).
- Submit the entire JSON object to
POST /submissionand hope that it works!
Do you need USEBIO?
Yes! While it’s true that you can technically skip (1) above and generate the JSON object from scratch, it’s very much not advisable. It will be a lot simpler for you to create the well-documented USEBIO file than to try and figure out our largely undocumented JSON format. That will also mean that you are compatible with third-parties that use USEBIO. And we may also want to add fields to the JSON, which you wouldn’t necessarily know about.
Check session date
This endpoints checks a date for two things: whether this club/county has already submitted a session for this date (in which case it might be a duplicate and a warning could be given); and whether this club/county has registered for a Sim Pairs event on this date (in which they should be prompted for whether they want to submit it to the Sim too).
HTTP Request
GET https://www.ebu.co.uk/members/api-3.1/session-date/20161005
{
"response": {
"login": "county",
"Sims": [
{
"ID": "000181",
"Description": "British Autumn Pairs Wednesday"
}
],
"Duplicates": 1,
"process_time": "0.4424s"
}
}
<response>
<login>county</login>
<Sims>
<ID>000181</ID>
<Description>British Autumn Pairs Wednesday</Description>
</Sims>
<Duplicates>1</Duplicates>
<process_time>0.4424s</process_time>
</response>
response
login,county
Sims,000181,British Autumn Pairs Wednesday
Duplicates,1
process_time,0.4424s
GET https://www.ebu.co.uk/members/api-3.1/session-date/{date}
Query parameters
| Parameter | Default | Description |
|---|---|---|
| date | none | The date you’re interested in, in the format yyyymmdd. |
Response
| Field | Description |
|---|---|
| Sims | A list of Sims that we’re registered for on this date (will almost always be one), along with the name and ID. |
| Duplicates | A count of the number of other sessions we’ve submitted for this date. |
Check players
This endpoint checks a list of players to make sure that the EBU numbers match the surname. This check is strongly recommended before a submission is sent, to limit the chances of a submission failing (and also to speed it up).
There are a few things to note:
- Guests (people with EBU number ‘88888888’) always match successfully.
- Anonymous people also always match, since we cannot rely on their surname.
- People with multiple surnames e.g. de la Tour or van Garderen require the full name so will mismatch if you supply just Tour or Garderen.
- It’s more lenient in reverse, though. If you submit de la Tour and the name on our database is Tour then it will match successfully, and return the found version in the sub_surname field. This is because some clubs add the forenames in the surname field and would otherwise get constant warnings: “Bob Hoskins” will match “Hoskins”.
HTTP Request
POST https://www.ebu.co.uk/members/api-3.1/submission/check-players
We're using this request:
[
{
"ebu": "00987654",
"surname": "Shears"
},
{
"ebu": "00987653",
"surname": "NotExist"
},
{
"ebu": "00987652",
"surname": "Cooke"
}
]
{
"response": {
"login": "county",
"Players": [
{
"ebu": "00987654",
"surname": "Shears",
"check": "cd44d12da"
},
{
"ebu": "00987653",
"surname": "NotExist",
"bad_ebu": 1
},
{
"ebu": "00987652",
"surname": "Cooke",
"found_surname": "Cook",
"mismatch": 1
}
],
"BadEBUs": 1,
"Mismatches": 1,
"process_time": "1.9095s"
}
}
<response>
<login>county</login>
<Players>
<ListItem>
<ebu>00987654</ebu>
<surname>Clark</surname>
<check>cd43d12da</check>
</ListItem>
<ListItem>
<ebu>00987653</ebu>
<surname>NotExist</surname>
<bad_ebu>1</bad_ebu>
</ListItem>
<ListItem>
<ebu>00987652</ebu>
<surname>Cooke</surname>
<found_surname>Cook</found_surname>
<mismatch>1</mismatch>
</ListItem>
</Players>
<BadEBUs>1</BadEBUs>
<Mismatches>1</Mismatches>
<process_time>1.9095s</process_time>
</response>
This one comes out horribly, so don't even try!
POST https://www.ebu.co.uk/members/api-3.1/submission/check-players
Query parameters
| Parameter | Default | Description |
|---|---|---|
| data | none | A JSON-encoded string containing an array of player objects, each containing the values 'ebu’ and 'surname’. See the example query to the right. |
Response
Returns a list of Players items, with the following information:
| Field | Description |
|---|---|
| ebu | The EBU number supplied. |
| surname | The surname supplied. |
| mismatch | A boolean to say if the name did not match the EBU number. |
| found_surname | In the case of a mismatch, this identifies the surname found. |
| bad_ebu | A boolean to say if this EBU number does not exist on the database. |
| check | A check key which can be used during the final submission to bypass the surname check. See below for details. |
Additionally, the response tells you how many mismatches there were and how many non-existent EBU numbers, to save you looking through them all.
What are Check Keys?
When an EBU number matches a surname, a Check Key is returned. This is a very simple hash of the EBU number and surname, and is used to verify that this combination has been checked by the system and doesn’t need to be checked again. Therefore, when you submit this to the final submission routine (below), it’ll save a few seconds.
These won’t change so long as the EBU number and surname don’t change, so you can store these offline if you wish and skip the POST /submission/check-players step in the submissions process when you have no new players.
Submit session
This endpoint submits session data. A description of what you need to do to prepare for this step can be found at the top of this section. We will reiterate that it’s very much advisable that you let the EBU know what you’re developing so that we can assist you in checking that everything is being done correctly.
HTTP Request
POST https://www.ebu.co.uk/members/api-3.1/submission
POST https://www.ebu.co.uk/members/api-3.1/submission
Query parameters
| Parameter | Default | Description |
|---|---|---|
| data | none | A JSON-encoded string containing all the session data. This needs to be in the same format as the EBU’s parser outputs. |
Response
| Field | Description |
|---|---|
| failure | Lots of possible failure messages can be returned, all of which should halt submission. |
| warnings | If a player has no check key supplied, we will have to check it again and will print a warning. You should try to avoid letting this happen, as it will slow down the process. |
| SessionID | If everything is successful, the new session’s ID will be returned in this field. |
Sim Pairs
These procedures deal with Simultaneous Pairs events and how clubs can register and submit results to them.
Get list of Sims
There are two versions of this endpoint. One is when you’re logging in as a club or county and lists all the sim pairs events coming up, with information about whether this club/county is registered or not. The other is when you’re logging in as a member and lists all the sim pairs for which you are the nominated contact, along with links to where to access the files.
As a reminder of how this works, clubs register for Sim Pairs events and nominate a member who should have access to the deal files and commentary. That member then logs in to their own My EBU to get access to the files. Counties and non-affiliated (usually Scottish or Welsh) clubs differ in that they have access to the deal files through their own account and do not need to nominate a member.
HTTP Request (for clubs/counties)
GET https://www.ebu.co.uk/members/api-3.1/sims
{
"response": {
"login": "club",
"Events": [
{
"ID": "000001",
"Description": "Sim Pairs Monday",
"Date": "20170904120000",
"Registered": "1",
"Contact": "00987654",
"NoBooklets": "0",
"Name": {
"Surname": "s'Aveyes",
"Forenames": "Hill"
},
"Booklets": "3",
"Travellers": "0"
},
{
"ID": "000002",
"Description": "Sim Pairs Tuesday",
"Date": "20170905120000",
"NoBooklets": "0",
"Registered": "0"
},
],
"Registered": 1,
"process_time": "1.8222s"
}
}
<response>
<login>club</login>
<Events>
<ID>000001</ID>
<Description>Sim Pairs Monday</Description>
<Date>20170904120000</Date>
<Registered>1</Registered>
<Contact>00987654</Contact>
<NoBooklets>0</NoBooklets>
<Name>
<Surname>s'Aveyes</Surname>
<Forenames>Hill</Forenames>
</Name>
<Booklets>3</Booklets>
<Travellers>0</Travellers>
</Events>
<Events>
<ID>000002</ID>
<Description>Sim Pairs Tuesday</Description>
<Date>20170905120000</Date>
<NoBooklets>0</NoBooklets>
<Registered>0</Registered>
</Events>
<Registered>1</Registered>
<process_time>1.8222s</process_time>
</response>
response
login,club
Events,000001,Sim Pairs Monday,20170904120000,1,00987654,0,s'Aveyes,Hill,3,0
Events,000002,Sim Pairs Tuesday,20170905120000,0,0
Registered,1
process_time,1.8222s
GET https://www.ebu.co.uk/members/api-3.1/sims
Response
Returns a list of Events with the following fields:
| Field | Description |
|---|---|
| ID | The ID of the Sim Pairs session. Every day has a unique ID. |
| Description | The description of this event. |
| Date | The date of the event. |
| Registered | Booklean saying whether this club/county is registered for this event. |
| Contact | The EBU number of the contact who should have access to the files. |
| NoBooklets | A boolean value for if there are no booklets available in this event. Can be used to prevent clubs ordering booklets that don’t exist. |
| Name | Surname and Forenames fields for the contact. |
| Booklets | The number of booklet packets ordered. Booklets come in packets of 10. |
| Travellers | A boolean value for whether travellers have also been ordered. |
There is also a Registered field at the top level, which gives a count of the number of events this club is registered for.
HTTP Request (for members)
GET https://www.ebu.co.uk/members/api-3.1/sims
{
"response": {
"login": "member",
"Events": [
{
"ID": "000001",
"Description": "Sim Pairs Monday",
"Folder": "20170904_abcdefghijk",
"Date": "20170904120000",
"Club": "EBU Bridge Club",
"Files": [
"20170904_all.zip",
"20170904_commentary.pdf",
"20170904_commentary_booklet.pdf",
"20170904_curtains_back.pdf",
"20170904_curtains_front.pdf",
"20170904_deal.bri",
"20170904_deal.csv",
"20170904_deal.dlm",
"20170904_deal.dup",
"20170904_deal.pbn",
"20170904_travellers_numbered.pdf",
"20170904_travellers_unnumbered.pdf"
]
}
],
"process_time": "1.2444s"
}
}
<response>
<login>member</login>
<Events>
<ID>000001</ID>
<Description>Sim Pairs Monday</Description>
<Folder>20170904_abcdefghijk</Folder>
<Date>20170904120000</Date>
<Club>EBU Bridge Club</Club>
<Files>
<ListItem>20170904_all.zip</ListItem>
<ListItem>20170904_commentary.pdf</ListItem>
<ListItem>20170904_commentary_booklet.pdf</ListItem>
<ListItem>20170904_curtains_back.pdf</ListItem>
<ListItem>20170904_curtains_front.pdf</ListItem>
<ListItem>20170904_deal.bri</ListItem>
<ListItem>20170904_deal.csv</ListItem>
<ListItem>20170904_deal.dlm</ListItem>
<ListItem>20170904_deal.dup</ListItem>
<ListItem>20170904_deal.pbn</ListItem>
<ListItem>20170904_travellers_numbered.pdf</ListItem>
<ListItem>20170904_travellers_unnumbered.pdf</ListItem>
</Files>
</Events>
<process_time>1.2444s</process_time>
</response>
response
login,member
Events,000001,Sim Pairs Monday,20170904_abcdefghijk,20170904120000,EBU Bridge Club,20170904_all.zip,20170904_commentary.pdf,20170904_commentary_booklet.pdf,20170904_curtains_back.pdf,20170904_curtains_front.pdf,20170904_deal.bri,20170904_deal.csv,20170904_deal.dlm,20170904_deal.dup,20170904_deal.pbn,20170904_travellers_numbered.pdf,20170904_travellers_unnumbered.pdf
process_time,1.2444s
GET https://www.ebu.co.uk/members/api-3.1/sims
Response
Returns a list of Events with the following fields. Note that you can only get these for future sims events.
| Field | Description |
|---|---|
| ID | The ID of the Sim Pairs session. Every day has a unique ID. |
| Description | The description of this event. |
| Folder | The folder where the files for this event can be found (if available). For example, if the folder is called ‘foldername’ then you can find the files at http://www.ebu.co.uk/sims/events/foldername. The folder name includes a random string to make it hard/impossible for someone to guess the location of the files. |
| Date | The date of the event. |
| Club | The club which registered you. |
| Files | A list of file names that can be found inside the above folder. Hopefully these are self-explanatory. |
Register for a Sim
This endpoint lets you register for a Sim Pairs event, and order booklets. It can also be used to update an existing registration - just send the new information and it will overwrite the original. You cannot unregister for a Sim Pairs event online (this is to stop people from registering just to gain access to the hand records). To unregister, contact Leszek in the office.
HTTP Request
POST https://www.ebu.co.uk/members/api-3.1/sims/{id}
{
"response": {
"login": "club",
"success": "Registered for event",
"booklet_success": "Booklets ordered/amended",
"process_time": "1.4411s"
}
}
<response>
<login>club</login>
<success>Registered for event</success>
<booklet_success>Booklets ordered/amended</booklet_success>
<process_time>1.4411s</process_time>
</response>
response
login,club
success,Registered for event
booklet_success,Booklets ordered/amended
process_time,1.4411s
POST https://www.ebu.co.uk/members/api-3.1/sims/{id}
Query parameters
| Parameter | Default | Description |
|---|---|---|
| contact | none | The EBU number of the nominated contact who will have access to the files. Not required for a county login. |
| booklets | 0 | Number of packets of booklets that the club wants. Booklets come in packets of 10, so don’t get this confused with individual booklets or it will be expensive! |
| travellers | 0 | Boolean value for whether the club wants travellers to be included with the booklets. |
Response
| Field | Description |
|---|---|
| success | Whether the request was successful or not. |
| booklet_success | Whether the booklets were successfully ordered or not. You can register for an event up to the day of the event, but booklets must be ordered earlier than this. If a club is too late to order booklets online, they can contact Leszek in the EBU office who may be able to help. |
Add a session to a Sim
This endpoint lets you push a session that has already been submitted into a Sim Pairs event that the club is registered for on the same day. This is typically not necessary, since it is done at the same time as submission of the session, but sometimes it is omitted by mistake and this is a way to recover.
HTTP Request
POST https://www.ebu.co.uk/members/api-3.1/sim/000100/session/00987654-000001
{
"response": {
"login": "club",
"success": "Session processed (ID #000100)",
"process_time": "2.2547s"
}
}
<response>
<login>club</login>
<success>Session processed (ID #000100)</success>
<process_time>2.2547s</process_time>
</response>
response
login,club
success,Session processed (ID #000100)
process_time,2.2547s
POST https://www.ebu.co.uk/members/api-3.1/sim/{id}/session/{sid}
Query parameters
| Parameter | Default | Description |
|---|---|---|
| id | none | The ID of the Sim Pairs event. |
| sid | none | The ID of the Session that we want to add to this sim. |
Remove a session from a Sim
This endpoint lets you remove a session from a Sim Pairs event.
HTTP Request
DELETE https://www.ebu.co.uk/members/api-3.1/sim/000100/session/00987654-000001
{
"response": {
"login": "club",
"success": "Session removed",
"process_time": "0.7103s"
}
}
<response>
<login>club</login>
<success>Session removed</success>
<process_time>0.7103s</process_time>
</response>
response
login,club
success,Session removed
process_time,0.7103s
DELETE https://www.ebu.co.uk/members/api-3.1/sim/{id}/session/{sid}
Query parameters
| Parameter | Default | Description |
|---|---|---|
| id | none | The ID of the Sim Pairs event. |
| sid | none | The ID of the Session that we want to remove from this sim. |
Leagues and Knockouts
We don’t anticipate any interest in the procedure calls to interact with the two web applications EBULeague and EBUKnockout. If we’re wrong about this then drop us a line and tell us why you want to develop an integration, rather than using the existing user interface.